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，契约就从技术约定退化成口头承诺。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
