HTML质量验证必须自动化：HTMLHint用于增量检查改动文件，htmlproofer在构建产物上验证链接与资源有效性，CI中需区分阻塞规则与告警规则，避免误报阻塞流程。
HTML代码质量回归验证不靠人眼扫，得靠自动化测试用例在每次提交时自动跑一遍 —— 否则改个 <img> 标签漏了 alt，上线后才被运营投诉，就晚了。
HTMLHint 配合 git diff 做增量检查
全量扫描所有 .html 文件效率低、噪音多，尤其对历史遗留项目。真正实用的做法是只检查本次提交改动的 HTML 文件。
- 用
git diff --name-only HEAD~1 -- '*.html'提取新增/修改的 HTML 路径 - 把结果传给
npx htmlhint，例如：npx htmlhint $(git diff --name-only HEAD~1 -- '*.html' | tr '\n' ' ') - CI 中建议加
--quiet参数，避免无错误时输出冗余路径列表 - 注意：如果 PR 跨多个 commit，
HEAD~1会漏检，应改用origin/main...HEAD（即 base 分支到当前头的 diff）
HTMLProofer 验证链接与资源有效性
htmlproofer 不是 Linter，它真去 HTTP 请求每个 <a href> 和 <img src>，适合回归验证「页面是否还能打开」这类问题。
- 本地运行示例：
htmlproofer ./_site --check-html --url-ignore "/google.com/, /#/" -
--check-html会解析 HTML 并报告语法错误（如未闭合标签），但不如htmlhint细粒度 -
--url-ignore必须填，否则 CI 中遇到第三方不可控链接（如微信二维码跳转页）会直接失败 - 静态站点生成器（如 Jekyll/Hugo）输出目录（如
_site或public）才是htmlproofer的输入目标，不是源码目录
CI 流程中如何避免“误报阻塞”
HTML 质量工具一旦配置不当，很容易让一次无关紧要的提交（比如改了个文案）因某条过期外链失败而卡住整个 PR 流程。
立即学习“前端免费学习笔记（深入）”；
- 把
htmlhint设为非阻塞步骤（GitHub Actions 中用continue-on-error: true），只记录 warning - 对
htmlproofer设置宽松阈值：--http-status-ignore "429,503"，避免因目标服务临时不可用导致失败 - 区分环境：预发环境（staging）跑严格检查；PR 环境允许部分忽略项，但必须记录日志供人工复核
- 关键点：所有 HTML 质量检查都应在构建产物上执行，而非源码 —— 源码里可能有模板语法（如
{% if %}），htmlproofer会直接报错
真正难的不是加一条 run: npx htmlhint，而是决定哪些规则必须硬性拦截、哪些只告警、哪些该动态忽略 —— 这些边界线，得跟着团队交付节奏和线上故障史一起调。
