在高频发布周期中，确保HTML代码质量是持续交付的关键环节，但全量扫描所有HTML文件的开销实在过高。当项目积累了几百个页面、模板或静态生成产物后，运行 htmlproofer ./build 或 npx htmlhint "**/*.html" 这类命令往往需要耗费数分钟——这直接拖慢了合并与部署的节奏。真正高效的增量检测并非简单“少扫一些”，而是精准锁定本次提交中实际被修改过的HTML路径，从而跳过所有未变更文件的解析、规则匹配及报告生成等步骤。
增量检测为何比全量扫描更具关键性
逻辑其实非常直观：每次提交往往只改动少量文件，但若对整个项目的每一行HTML重新检查，时间成本完全不成比例。在高频发布场景下，这种低效尤其不可接受——一个耗时数分钟的CI任务会直接拉低整个流水线的反馈速度，影响开发效率。
Git diff 与文件白名单是落地增量检测的前提
然而，工具本身并不知道哪些HTML文件发生了变化，必须依赖Git提供上下文。这里有一个常见误区：直接使用 git ls-files *.html 会扫描所有历史目录，甚至包含已删除的文件，导致误报和漏检频发。
正确做法：使用
git diff --name-only HEAD~1 HEAD -- "*.html"获取本次commit中新增或修改的HTML路径。注意用双引号包裹通配符，避免shell提前展开。增加一层过滤：排除构建产物目录，例如
grep -v "^dist/" | grep -v "^build/"，避免检查打包后生成的HTML，这些文件通常不是维护目标。若在CI环境（如GitHub Actions）中，推荐优先使用
github.event.pull_request.base.sha和github.event.pull_request.head.sha进行diff，而非HEAD~1。原因在于rebase后sha会偏移，容易导致检测范围出错。
HTMLProofer 与 HTMLHint 的增量调用差异
这两个工具的调用方式差异较大，需要分别处理。
htmlproofer 原生不支持单文件模式下的链接或图片资源校验——它默认需要检查整个目录的相对引用关系。因此，增量调用时必须带上 --url-ignore 和 --disable-external，否则会因缺失上下文路径而大量报404。一个可用的命令示例：
htmlproofer $(git diff --name-only HEAD~1 HEAD -- "*.html" | grep -v "node_modules|dist|build") --check-html --disable-external --url-ignore "/api/,/static/"
相比之下，htmlhint 更加轻量——它可以直接对单个文件运行，无需依赖关系。增量命令示例：
git diff --name-only HEAD~1 HEAD -- "*.html" | xargs -r npx htmlhint
这里的 -r 参数能防止git diff无输出时xargs报错——细节虽小，但在实际运行中至关重要。
需要特别留意：HTMLProofer对 alt、href 等属性的检查依然有效，但跨文件锚点（例如 a href="#section2"）在增量模式下无法验证目标是否存在。这类问题仍需保留在全量扫描阶段来处理。
忽略列表必须动态生成，避免硬编码
在高频发布场景下，临时忽略项（如测试页面、灰度路由、第三方嵌入片段）经常随PR一起变化。若将这些忽略项硬编码到配置文件的 ignore_urls 或 ignore_files 中，不是漏检就是误拦，效果不佳。
推荐做法：在CI脚本中通过
grep -q "DISABLE_HTML_CHECK" .git/COMMIT_EDITMSG && exit 0快速跳过特定提交。或从PR标题或描述中提取标记，例如匹配
[skip-html]，再动态注入--url-ignore参数。硬编码的忽略路径（如
"docs/examples/legacy/**/*.html"）仅适用于长期稳定的目录结构——一旦目录迁移，就会形成隐蔽的质量缺口，等发现时往往已为时过晚。
说到这里，真正困难的并非跑通增量命令本身，而是让每位开发者理解：所谓“本次改动的覆盖范围”，不仅包括自己修改的若干文件，还涉及它们所引用的模板、组件、数据源路径——这些隐式依赖决定了该扫描什么、不该扫描什么。一旦遗漏一个 include 路径，整套增量逻辑就可能形同虚设。
