pre-commit可通过集成htmlhint实现HTML提交前校验：安装htmlhint并配置规则，用script类型钩子调用htmlhint "$@"精准检查暂存文件，配合files排除生成目录、--format=compact输出可读错误，并结合prettier自动修复。
本地 Git 提交前就该拦住低质量 HTML —— 不靠 GitHub Actions 延迟到远程，也不依赖人工审查。核心在于：用 pre-commit 钩子 + 轻量级 HTML 检查工具，在 git commit 执行瞬间完成校验，失败则中断提交。
怎么让 pre-commit 拦住不符合规范的 HTML？
关键不是装一堆工具，而是选对能嵌入 Git 生命周期的检查器。推荐 htmlhint（轻量、规则可配、支持 CLI），配合 pre-commit 框架统一管理。
-
npm install -D htmlhint，确保本地有可执行的htmlhint二进制 - 在项目根目录写
.htmlhintrc，明确启用你真正在意的规则，比如"attr-no-duplication": true、"attr-value-double-quotes": true，避免默认全开导致误报 - 在
.pre-commit-config.yaml中声明钩子：repos: - repo: https://github.com/awslabs/git-secrets rev: v1.5.0 hooks: - id: htmlhint # 注意：需自行封装成 pre-commit 兼容脚本，或使用社区版 htmlhint hook或者更稳妥的做法：用script类型直接调htmlhint，绕过第三方 hook 维护风险
为什么不能只用 npm script 或 husky？
因为 husky 的 pre-commit 钩子本质是 shell 脚本，它不感知 Git 暂存区（staging）的真实文件范围 —— 它会扫整个 src/ 目录，哪怕你只改了一个 index.html。而 pre-commit 框架默认只把本次 git add 的文件传给检查器，精准、高效、不误伤。
- 如果你用
npm run lint:html做提交前检查，必须手动保证命令只作用于暂存文件，否则 CI 和本地行为不一致 -
pre-commit自动传递$1 $2 ...（即暂存文件路径列表），htmlhint可直接受参：htmlhint "$@" - 若项目混用多种语言，
pre-commit还能统一管理 ESLint、Prettier、Secrets 扫描等，避免多套钩子打架
HTML 检查容易踩的坑有哪些？
不是所有 HTML 问题都适合提交前拦截。过度检查会拖慢开发节奏，甚至阻断合法代码。
立即学习“前端免费学习笔记（深入）”；
- 避免检查生成文件：确认
.pre-commit-config.yaml中的files正则排除了dist/、build/、node_modules/等目录 - 忽略模板片段：像
.hbs、.ejs、.vue单文件组件里的 HTML 片段，htmlhint无法正确解析，应跳过或换专用 linter - 警惕自闭合标签误报：比如
<img src="x" alt="基于本地Git工作流的HTML代码质量提交前阻断逻辑设计" >在 HTML5 下合法，但某些旧版htmlhint规则会强制要求<img src="x" alt="基于本地Git工作流的HTML代码质量提交前阻断逻辑设计" >，需关掉attr-value-not-empty类易冲突规则 - 注意编码问题：如果团队用 GBK 编码的遗留 HTML 文件，
htmlhint默认只认 UTF-8，会直接报错退出，此时要么转码，要么加--encoding=gbk参数（需确认版本支持）
本地阻断后，开发者该怎么快速修复？
阻断不是目的，给出可操作反馈才是。别只甩一行 htmlhint: 3 errors found。
- 在
pre-commit钩子里加--format=compact参数，让错误带行号和简短描述，例如：index.html:12:7: Attribute "class" is not allowed on element "div" - 搭配
prettier自动格式化：对 HTML 结构类问题（缩进、引号、空格），用prettier --write一键修正，再由pre-commit提交修正后的版本 —— 这比让人肉改更可持续 - 把常见错误映射成文档链接：比如检测到内联样式，输出提示 “建议提取为 CSS 类，参考：/docs/html-best-practices#inline-styles”
真正难的不是加个钩子，而是定义清楚：哪些 HTML 问题必须卡在本地，哪些留给 CodeQL 或 GitHub Code Quality 在 PR 阶段处理。边界模糊的地方，反而最容易被绕过或反复报错。
