先抛出一个结论:很多人觉得配置了 lint-staged 就能自动修复所有代码文件,但在实际开发中会发现,它默认并不会处理 .html 文件。如果你直接在图里写 "*.html": ["eslint --fix"],基本会直接报错——因为 ESLint 根本就不是为 HTML 设计的工具。
要想让 HTML 文件在提交代码前被自动格式化,你需要手动配置规则、安装正确的工具链,并且确保 Husky 这个“提交门卫”确实接到了执行指令。

核心配置其实很简单:要么用 prettier 做纯格式化,要么用 htmllint 或 html-validate 做语义校验。不过前提是,你得确认这些工具的 CLI 已经正确安装并可用。
为什么 eslint 对 .html 文件无效
ESLint 本质上只是一个 Ja vaScript 的静态分析工具,它只能识别 JS 的 AST 结构。.html 文件里包含的标签、属性、内联脚本和样式,ESLint 根本无法解析。即使安装了 eslint-plugin-html 这样的插件来“扩展能力”,它也最多只能处理 标签内的 JS 代码,而对标签嵌套是否合理、语义是否准确、可访问性是否达标等关键问题,它完全无能为力。
- 典型踩坑场景:你满怀期待地执行
eslint --fix *.html,结果终端报错Cannot read file ... no parser registered,任务直接中断。 - 实际项目中的常见问题:无论是 Vue/React 单文件组件里的
部分,还是纯静态 HTML 页面,都可能遇到这个 ESLint 无法处理的棘手问题。 - 可以选择的两个方向:要么只做代码格式化(推荐用
prettier),要么选择专门为 HTML 设计的校验工具(比如htmllint或html-validate)。
prettier 是最轻量可靠的 HTML 格式化选择
如果你的需求比较纯粹,只是想统一缩进、引号、换行这些代码格式问题,那么 prettier 无疑是最省心的方案。它开箱即用,不需要折腾额外插件,对项目的影响也最小。
- 先安装依赖:执行
npm install --sa ve-dev prettier。 - 再配置 lint-staged:在
package.json的lint-staged配置项中添加"*.html": ["prettier --write"]。 - 注意文件路径:如果你的 HTML 文件存放在子目录中,比如
public/目录下,那么 glob 匹配模式需要写成"public/**/*.html",否则无法匹配到文件,配置就相当于白写。 - 性能完全不用担心:Prettier 处理一个 HTML 文件通常只需要 10 到 50 毫秒,对提交速度几乎没有任何影响。
需要语义或可访问性检查?用 html-validate
当项目标准提升,比如需要符合 WCAG 无障碍规范、检查标签是否合理嵌套、确保每个 img 标签都加了 alt 属性、或者禁止使用内联样式时,prettier 就显得力不从心了。这时候,你需要请出 html-validate 这位专业的“代码质检员”。
- 安装步骤:执行
npm install --sa ve-dev html-validate。 - 初始化配置:运行
npx html-validate --init,它会自动生成一个.htmlvalidate.json配置文件,免去你手动书写规则的麻烦。 - 配置 lint-staged:在配置中写入
"*.html": ["html-validate --output-format=string"]。 - 需要特别注意的一点:
html-validate默认只负责检测并报告问题,并不会自动修复。也就是说,它发现代码问题时会“打回”给你,让你手动修改。如果你想实现自动修复(比如自动给添加空alt="\"),要么自己写个脚本处理,要么放弃自动修复这个念头。 - 兼容性提示:某些规则,例如
valid-aria-role,依赖于较新的 DOM API。如果你的 CI 环境使用老版本的 Node.js,可能会遇到意外的报错。
husky 的 pre-commit 钩子必须显式触发 lint-staged
工具链都配置好了,结果提交代码时却发现“完全没反应”…… 这是最容易遇到的坑。根本原因在于:Husky 的钩子没有正确指向 lint-staged。
- 别再用老方法:Husky v8 及以上版本已经不再支持在
package.json的husky.hooks字段里配置钩子,那套方法已经彻底过时了。 - 正确的配置方式:在项目根目录执行
npx husky add .husky/pre-commit "npx lint-staged"。这会在.husky/pre-commit文件中写入一条执行命令。 - 务必验证一下:运行
cat .husky/pre-commit查看文件内容,你应该能看到类似npx lint-staged的命令。看到这个,才能放心地提交代码。 - 一个容易被忽略的细节:如果你的项目使用
pnpm管理依赖,那么命令应该写成pnpm exec lint-staged。如果继续使用npx,可能会因为找不到本地安装的包而导致命令执行失败。
聊到最后,HTML 文件的提交前拦截之所以容易出问题,根本原因在于“默认配置什么都没管”。很多人想当然地以为配个 eslint --fix 就万事大吉了。真正让这套机制稳定运行的关键在于以下三点:明确选择并配置好工具链(到底是 Prettier 还是 html-validate)、显式声明正确的文件匹配路径(确保不会遗漏任何文件)、最后再仔细验证一下 Husky 钩子是否被正确触发。这三者,一个都不能少。
