增量检测比全量扫描更关键，因其仅扫描本次提交修改的html路径，避免拖慢ci流水线；需结合git diff获取真实变更文件、过滤构建目录，并适配htmlproofer与htmlhint的调用差异。
增量检测为什么比全量扫描更关键
高频发布时，每次全量扫描所有HTML文件会拖慢CI流水线，尤其当项目有数百个页面、模板或静态生成产物时，htmlproofer ./build 或 npx htmlhint "**/*.html" 往往耗时数分钟——这直接卡住合并与部署节奏。真正有效的增量检测，不是“少扫一点”，而是只扫**本次提交真正修改过的HTML路径**，跳过未变更文件的解析、规则匹配和报告生成。
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；htmlhint 则可直接对单个文件运行，无依赖问题。
-
htmlproofer增量命令示例：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防止无输出时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路径，就可能让整套增量逻辑失效。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
