基于Husky与Lint-staged的HTML代码质量提交前拦截机制

lint-staged 默认不处理 .html 文件，因其未包含在默认 glob 模式中；需显式配置 “*.html”: [“prettier –write”] 等规则，并确保安装 Prettier 及其 HTML 支持插件，同时通过 Husky 正确绑定 pre-commit 钩子。

lint-staged 默认不处理 .html 文件，直接配置 "*.html": ["eslint --fix"] 会失败——因为 ESLint 不解析 HTML；要用 prettier 或 htmllint，且必须显式安装对应 CLI。

为什么 eslint 对 .html 文件无效

ESLint 的核心是 JavaScript AST 分析器，.html 文件里混着标签、属性、内联脚本和样式，它无法原生识别。即使用了 eslint-plugin-html，也只支持内联 <script> 块，不校验结构、语义或可访问性。

• 常见错误现象：eslint --fix *.html 报错 Cannot read file ... no parser registered
• 真实使用场景：Vue/React 项目中单文件组件的 <template> 或纯静态 HTML 页面
• 替代方案只有两类：格式化（prettier）或专用校验（htmllint、html-validate）

prettier 是最轻量可靠的 HTML 格式化选择

如果你只关心缩进、引号、换行等基础格式，prettier 开箱即用，无需额外插件。

• 确保已安装：npm install --save-dev prettier
• 在 package.json 的 lint-staged 配置中加入："*.html": ["prettier --write"]
• 注意路径匹配：如果 HTML 在子目录（如 public/*.html），写成 "public/**/*.html"，否则匹配不到
• 性能影响极小：Prettier 对单个 HTML 文件处理通常在 10–50ms 内

需要语义/可访问性检查？用 html-validate

当项目要求符合 WCAG、校验标签嵌套、必填属性（如 alt）、禁止内联样式时，prettier 不够用，得上 html-validate。

立即学习“前端免费学习笔记（深入）”；

• 安装：npm install --save-dev html-validate
• 初始化配置：npx html-validate --init（生成 .htmlvalidate.json）
• 配置 lint-staged："*.html": ["html-validate --output-format=string"]
• 关键坑：html-validate 默认不自动修复，只能报错拦截；如需自动修复（如加 alt=""），得配合自定义 script 或放弃自动修复
• 兼容性注意：某些规则（如 valid-aria-role）依赖最新版 DOM APIs，在 CI 中可能因 Node 版本低而报错

husky 的 pre-commit 钩子必须显式触发 lint-staged

很多人配完 lint-staged 却没生效，根本原因是 Husky 钩子没正确定向到它。

• 不要只改 package.json 里的 husky.hooks 字段——Husky v8+ 已弃用该方式
• 正确做法：npx husky add .husky/pre-commit "npx lint-staged"
• 验证钩子是否生效：cat .husky/pre-commit 应看到类似 npx lint-staged 的命令行
• 容易忽略的点：如果项目用 pnpm，命令要改成 pnpm exec lint-staged，否则 npx 可能找不到本地安装的二进制

HTML 文件的提交拦截最容易卡在「以为配了 ESLint 就万事大吉」，实际连文件都读不进去。真正起作用的是明确指定工具链 + 显式声明匹配路径 + 验证钩子执行流——三者缺一不可。