HTMLHint 代码检查工具必须在 pre-commit 钩子、编辑器保存以及 CI 流水线这三个环节同步生效。通过 husky 配置 npx htmlhint 校验命令，启用 doctype-first 等 3–5 条高危规则，统一 .htmlhintrc 配置文件与 glob 路径，从而在提交前形成强校验卡点。
htmlhint 绝非装饰品，它必须同时在 pre-commit 钩子、编辑器保存以及 CI 流水线中生效，否则技术债务只会越积越厚。
如何让 htmlhint 在提交前真正拦截问题？
本地提交前不做检查，相当于将校验责任完全推给 CI 流程——然而当 CI 报错时，开发者往往已经切换分支、开始编写新功能，修复意愿和上下文均已中断。关键在于，在按下 git commit 命令的瞬间就将问题拦截下来。
- 使用
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"这类无意义标识 - 关键语义区域（如主内容区、导航栏）强制使用标准 HTML 标签并配合
role属性双重保障，例如，而不是仅依赖class="main-content"进行推断 - 测试脚本中禁止使用
document.querySelector(".btn-primary")进行定位，必须采用getByTestId或getByRole方法 - 设计交付物需明确标注“此处必须为
”，不能只写“顶部导航区”——语义意图必须可执行、可校验
真正困难的并非制定规则，而是让每条规则在开发者敲下 git commit 的瞬间立即生效。一旦某次提交绕过了 pre-commit 钩子，契约便从技术约束退化为口头承诺。
