HTML代码质量考核必须在提交和CI两个节点卡死，pre-commit用html-validate拦截img缺alt、title为空等结构问题，CI用htmlhint全量扫描并校验SSR输出，确保语义、无障碍与SEO不退化。
HTML代码质量考核必须在代码提交和CI构建两个节点卡死，否则语义错误、无障碍缺陷、SEO失效等问题会直接流入生产环境——这些错误不会导致构建失败，但会让Lighthouse评分暴跌、屏幕阅读器无法导航、搜索引擎拒收页面。
pre-commit 阶段用 html-validate 拦截基础结构问题
本地提交前就该挡住 <img> 缺 alt、<title> 为空、<div> 套 <h1> 这类低级但高危问题。html-validate 比 HTMLHint 更适合 pre-commit，因它支持自定义规则且输出可被 husky 直接消费。
- 在项目根目录执行
npm install html-validate --save-dev，不要全局安装 - 配置
.htmlvalidate.json（注意不是 .htmlhintrc），启用三条底线："require-title": "error"、"require-alt-attribute": "error"、"no-restricted-elements": ["div > h1", "div > h2"] - 用 husky + lint-staged 绑定：
lint-staged: {"**/*.html": ["html-validate --config .htmlvalidate.json"]} - 常见坑：VS Code 的 Live Server 打开
index.htm文件时，后缀不是.html，html-validate 不触发；务必统一用.html后缀
CI 构建阶段用 htmlhint 覆盖团队工程规范
pre-commit 只能拦住开发者本地改的文件，CI 阶段要全量扫描所有 HTML，尤其覆盖 SSR 模板、Figma2Code 输出、静态页等易被忽略路径。htmlhint 规则更细粒度，适合做“团队风格守门员”。
- CI 脚本中显式调用：
npx htmlhint src/**/*.html --config .htmlhintrc，不依赖全局命令 -
.htmlhintrc必须放在项目根目录，内容为纯 JSON，禁用注释和尾逗号；关键规则包括："attr-lowercase"、"tag-pair"、"id-unique"、"inline-script-disabled" - 老项目别一上来就 fail on warning，先设
"reporter": "unix"，再用grep -q "error"控制 exit code - 若 CI 报“找不到配置”，大概率是工作目录不是项目根目录——在流水线脚本开头加
cd $(git rev-parse --show-toplevel)
灰度与 SSR 场景下 HTML 片段校验失效怎么办
html-validate 和 htmlhint 默认校验完整文档，但 Storybook、Jest 渲染的组件片段只有 <div class="card">...，工具直接跳过——这就导致灰度流量上线后，无障碍测试才发现 <img> 没 alt。
立即学习“前端免费学习笔记（深入）”；
- 对片段补最小合法结构：
<html><head><title>test</title></head><body>${fragment}</body></html> - 禁用
require-valid-document规则，改用require-semantic-elements、require-valid-lang等聚焦语义的规则 - SSR 模板若用 EJS 或 Nunjucks，确保校验的是构建后生成的 HTML（如
dist/index.html），不是源模板文件 - 若用 Next.js / Nuxt，需在
next.config.js中配置outputFileTracing: true，保证 CI 能读到所有产出 HTML
真正难的不是装工具，而是让每行 HTML 都承载语义意图：一个 <button> 缺 type="button" 可能引发表单意外提交，<img alt=""> 和 <img> 在无障碍层面是两种错误——前者是“有声明无内容”，后者是“未声明”。这些细节不会报错，但会悄悄拖垮用户体验和合规底线。
