从研发链条根源偿还技术债：HTML代码质量契约化落地实践

HTMLHint必须在pre-commit钩子、编辑器保存、CI流水线三处同时生效，通过husky配置npx htmlhint校验、启用doctype-first等3–5条高危规则、统一.htmlhintrc配置及glob路径，实现提交前强卡点。

htmlhint 不是摆设，它必须在 pre-commit 钩子、编辑器保存、CI 流水线三处同时生效，否则技术债只会越积越厚。

怎么让 htmlhint 真正在提交前拦住问题？

本地提交前不检查，等于把校验权完全交给 CI —— 而 CI 报错时，人已经切分支、写新功能，修复意愿和上下文都断了。 - 用 husky 配 htmlhint：执行 npx husky add .husky/pre-commit "npx htmlhint src/**/*.html --config .htmlhintrc"，确保钩子文件存在且可执行 - 配置里只开 3–5 条高危规则："doctype-first"、"tag-pair"、"attr-value-double-quotes"、"id-unique"、"attr-no-duplication" - 若项目含模板路径（如 views/*.html），需显式扩展 glob 模式，别只扫 src/**/*.html - 注意 Windows 用户可能因 shell 权限失败，建议统一用 npx simple-git-hooks 替代 husky v7+ 的复杂配置

为什么编辑器里标红了，CI 却不报错？

常见错误现象：VS Code 用 HTMLHint 插件标出 img 缺 alt，但 CI 跑 htmlhint 却沉默——说明环境或路径没对齐。 - .htmlhintrc 必须放在项目根目录，且 CI 启动命令要指定工作目录为根目录（例如 GitHub Actions 中加 working-directory: .） - 别依赖全局安装的 htmlhint，CI 脚本里一律用 npx htmlhint，避免版本漂移 - 如果用 puppeteer + axe-core 做快照扫描，注意它不校验语法结构，只查可访问性；htmlhint 和 axe 是互补关系，不是替代关系

如何让设计、测试、开发三方认同一份 HTML 质量契约？

契约不是文档，是能被工具验证的硬约束。 - 所有交互元素必须带 data-testid，命名与设计稿组件名一致，例如 data-testid="product-card-add-to-cart"，禁止 data-testid="button-1" 这类无意义 ID - 关键语义区域（如主内容、导航栏）强制使用标准标签 + role 双保险，例如 <main role="main"></main>，而非靠 class="main-content" 推断 - 测试脚本中禁止用 document.querySelector(".btn-primary") 定位，必须走 getByTestId 或 getByRole - 设计交付物需标注“此处必须为 <nav></nav>”，不能只写“顶部导航区”——语义意图必须可执行、可校验

真正难的不是写规则，而是让每条规则在开发敲下 git commit 的瞬间就起作用。一旦某次提交绕过了 pre-commit，契约就从技术约定退化成口头承诺。