高频发布周期下保障HTML代码质量的增量检测技术

增量检测比全量扫描更关键，因其仅扫描本次提交修改的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路径，就可能让整套增量逻辑失效。