HTML代码质量契约化：从源头清偿技术债

在前端工程化链条中，htmlhint 并非可选项，它必须在 pre-commit 钩子、编辑器保存、CI 流水线三处同时生效，否则 HTML 代码中的技术债只会越积越厚，最终拖累整个研发效率。

如何让 htmlhint 在提交前真正拦截问题？

本地提交前不执行检查，等于将校验权完全交给 CI —— 而 CI 报错时，开发者已切换分支、投入新功能开发，修复意愿和上下文都已断裂。关键在于敲下 git commit 的瞬间就将问题堵住，从源头保障 HTML 代码质量。

• 使用 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 时却保持沉默——根源在于环境或路径未对齐，导致 HTML 代码校验规则未统一生效。

• .htmlhintrc 必须放置在项目根目录，且 CI 启动命令需指定工作目录为根目录（例如在 GitHub Actions 中增加 working-directory: .）
• 避免依赖全局安装的 htmlhint，CI 脚本中统一使用 npx htmlhint，防止版本漂移引发校验结果不一致
• 若使用 puppeteer + axe-core 进行快照扫描，需注意其仅检查可访问性，不校验语法结构；htmlhint 与 axe 是互补关系，不可相互替代

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

契约不应停留于文档，而必须是可被工具验证的硬约束。以下几条规则可作为共识基础，推动 HTML 代码质量契约化落地：

• 所有交互元素必须携带 data-testid，命名与设计稿组件名保持一致，例如 data-testid="product-card-add-to-cart"，禁止使用 data-testid="button-1" 等无意义 ID
• 关键语义区域（如主内容区、导航栏）强制使用标准标签配合 role 双保险写法，例如
  ，而非依赖 class="main-content" 进行推断
• 测试脚本中禁止使用 document.querySelector(".btn-primary") 定位元素，必须通过 getByTestId 或 getByRole 进行选择
• 设计交付物需标注“此处必须为 ”，不能仅写“顶部导航区”——语义意图必须可执行、可校验

真正困难的并非制定规则，而是确保每条规则在开发者敲下 git commit 的瞬间立即生效。一旦某次提交绕过了 pre-commit 钩子，契约便从技术约定退化为口头承诺，HTML 代码质量也就失去了制度性保障。