HTML文件无原生语法校验能力，必须依赖html-validate等现代工具链介入pre-commit阶段，因其支持Vue/JSX指令识别，而htmlhint易在自定义元素、符号链接或内嵌模板场景下漏报或报错中断。
直接说结论：HTML 文件本身没有原生语法校验能力，必须靠外部工具链介入 pre-commit 阶段，且不能只依赖 htmlhint 这类基础检查——它对现代前端工程（如含 Vue 模板、JSX 片段、Tailwind 类名动态拼接）极易漏报或误报。
为什么 htmlhint 在 pre-commit 中常失效？
htmlhint 默认只做静态标签闭合、属性小写等基础规则，遇到以下情况会静默跳过或报错中断：
- 文件含
<script>块内嵌 JSX 或 Vue 模板语法（如v-if、{{ }}），直接抛Parse error: Unexpected token - 使用了自定义元素（如
<my-button>），未配置attr-req-value等白名单规则，误判为非法属性 - 路径中含符号链接（例如
src/views -> ../shared/views），htmlhint无法跟随解析，返回空结果 - 未显式指定
--config，默认读取项目根目录的.htmlhintrc，但 husky 启动时工作目录可能是子模块路径
推荐组合：html-validate + 自定义 ignore 规则
html-validate 是目前对现代 HTML 兼容性最好的校验器，支持 Vue/Svelte/JSX 指令识别，且能通过 ignore 配置跳过已知噪声区：
- 安装：
npm install html-validate --save-dev - 配置
.htmlvalidate.json，关键字段示例：{ "rules": { "no-inline-style": "error", "valid-charset": "error", "require-sri": ["warn", { "integrity": true }] }, "ignore": [ "**/node_modules/**", "**/dist/**", "**/public/index.html", // 跳过构建产物 "**/*.test.html" // 跳过测试用例 ] } - 在
.husky/pre-commit中调用：npx html-validate --config .htmlvalidate.json --max-warnings 0 src/**/*.html（--max-warnings 0表示 warning 也阻断提交）
如何处理内联脚本和样式中的 ESLint/Prettier 冲突？
HTML 文件里混写 JS/CSS 时，html-validate 不管逻辑，ESLint 也不认 <script> 块——这会造成质量检查断层。解决方案是分层拦截：
立即学习“前端免费学习笔记（深入）”；
- 用
eslint-plugin-html让 ESLint 扫描<script>和<style>块：npx eslint --ext .html src/**/*.html - 用
prettier --parser html格式化整个 HTML 文件（包括内联代码），避免prettier对<script>块误格式化成单行 - 顺序很重要：先
prettier格式化，再eslint检查，最后html-validate校验结构——否则eslint可能因缩进混乱报错，掩盖真实问题
容易被忽略的构建上下文陷阱
pre-commit 钩子运行在 Git 暂存区（staging area）而非工作区（working directory），这意味着：
-
git diff --cached --name-only获取的文件列表才是真实要提交的 HTML 文件，不要用find src -name "*.html"全量扫描 - 若某 HTML 文件已被
git add但后续又修改过，钩子看到的是暂存版本，不是你编辑器里最新的内容 - CI 流水线通常禁用钩子，所以必须把相同命令同步写入
package.json的scripts.lint:html，并在 CI 配置中显式调用，否则本地过检、CI 失败
