Git Hooks 可拦截 HTML 文件，需用 pre-commit 钩子配合 git diff --cached 过滤待提交的 .html/.htm 文件，调用 html-validate 增量检查；commit-msg 单独校验提交信息规范；pre-push 执行渲染快照比对；须在配置中声明 custom-elements 避免误报。
Git Hooks 本身不识别 HTML 文件类型，但你可以用它拦截 HTML —— 关键不是“能不能”，而是“用哪个钩子、调什么工具、怎么避免误拦”。
pre-commit 钩子必须只检查暂存区的 HTML 文件
直接扫描整个 src/ 或 public/ 目录会拖慢提交速度，且容易把未修改的旧文件也拉进来报错。正确做法是只处理 git diff --cached --name-only 输出的、当前即将提交的 HTML 文件。
- 用
grep -E '\.html?$'过滤出 HTML 类型（含.htm） - 空结果时跳过检查，避免无意义失败
- 别在
pre-commit里调html-validate全量扫描或启动 HTTP 服务 —— 它们响应慢、依赖多、易被杀进程
推荐用 html-validate 而不是 tidy-html5 或 vnu.jar
html-validate 是目前唯一能稳定跑在 pre-commit 场景下的 HTML 检查工具：Node.js 原生、支持增量模式、配置粒度细、错误定位准。而 tidy-html5 缺少现代语义校验（如 ARIA 属性拼写、role 合法值），vnu.jar 启动慢、JVM 内存占用高，本地提交时大概率超时退出。
- 安装：
npm install --save-dev html-validate - 最小配置
.htmlvalidate.json示例：{ "extends": ["html-validate:recommended"], "rules": { "valid-attr": "error", "no-inline-style": "warn", "require-sri": "off" } } - 钩子中调用：
npx html-validate --format=string --max-warnings=0 $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.html?$')
commit-msg 钩子要单独拆出来管提交信息，别塞进 pre-commit
HTML 文件本身不决定提交信息是否合规，但很多团队要求 HTML 变更必须带明确上下文（比如 “feat(header): add lang attr to html tag”）。这类规则如果硬塞进 pre-commit，会导致 HTML 检查失败时掩盖真正的提交信息问题，调试困难。
当用户提及 GitHub URL，或要求分析、审查、探索或理解任意 GitHub 项目、仓库或代码库时，请使用此技能。触发条件包括以下短语：“分析这个项目”、“看看这个仓库”、“analyze this repo”、“what does this project do”，或消息中包含任何 github.com URL。
立即学习“前端免费学习笔记（深入）”；
- 新建
.git/hooks/commit-msg，赋予执行权限 - 用
sed '1q;d'提取第一行，匹配^feat\|fix\|chore等前缀 - 若检测到 HTML 文件变更（
git diff-tree --no-commit-id --name-only -r HEAD -- | grep -q '\.html?$'），则强制要求信息含html或对应组件名 - 否则仅做基础长度检查（≥6 字符），避免过度约束非前端提交
pre-push 才该触发 HTML 渲染快照比对
想验证 HTML 修改是否导致视觉回归？别在 pre-commit 做截图或 Puppeteer 启动 —— 它们至少耗 2–5 秒，开发者会下意识 --no-verify 绕过。真正该做的是把渲染检查放到 pre-push，并限制只比对本次推送中涉及的 HTML 页面路径。
- 用
git diff origin/main...HEAD --name-only | grep '\.html?$'获取变更列表 - 启动轻量服务（如
serve -s dist -l 3001）并用 Playwright 截图（注意加--timeout=10000） - 比对逻辑走本地
pixelmatch，不传图到任何远程服务 - 失败时输出差异图路径 + exit 1，但允许加
--force-html-snapshot参数跳过（CI 环境默认不跳）
最常被忽略的一点：HTML 检查工具对自定义元素（如 <my-header></my-header>）和框架指令（如 v-if、ngIf）默认不识别，必须在 html-validate 配置里显式声明 custom-elements 或关闭对应规则，否则大量误报。这步不做，钩子第一天就会被全员禁用。
