HTML质量门禁需分阶段实施：pre-commit轻量检查暂存区HTML文件的结构与基础可访问性，pre-push深度扫描构建产物，CI/CD则专注补充SEO、HTTP头等上下文相关检查。
HTML代码质量门禁不能只靠浏览器手动检查，必须嵌入到 Git 工作流的 pre-commit 或 pre-push 阶段，用可执行、可复现的工具链拦截常见问题：未闭合标签、非法属性、无障碍缺失、内联样式/脚本硬编码等。
pre-commit 钩子里该跑哪些 HTML 检查？
本地提交前必须轻量、快速、只扫暂存区变更文件。重点检查结构合规性与基础可访问性，避免引入阻塞型耗时操作。
- 用
html-validate扫描git diff --cached --name-only --diff-filter=AM | grep "\.html$"输出的文件，配置规则如"no-inline-style"、"require-lang-attribute" - 禁止在钩子中调用
axe-core浏览器 API —— 它依赖 DOM 环境，pre-commit 里只能用其 CLI 版本axe（需额外安装 Node.js 依赖） - 别把
tidy当主力：它修复能力弱、输出格式不统一，且对现代语义化标签（如<dialog>、<details>）支持滞后 - 敏感信息扫描要加白名单：比如允许
<script src="https://cdn.jsdelivr.net/...">，但拒绝<script>var API_KEY = "xxx"</script>
pre-push 阶段才适合做深度 HTML 质量分析
pre-push 是本地最后一次拦截机会，可以接受 10–20 秒耗时，适合运行需要完整上下文或生成报告的检查。
- 用
pa11y-ci对本地起的服务（如npx serve -s dist -l 3000）发起无障碍扫描，触发条件是当前分支含dist/目录变更 - 校验
index.html中的<meta name="viewport">是否存在且值合法，用grep -q 'viewport' dist/index.html || exit 1 - 检查构建产物中是否残留
console.log或debugger：用grep -r "console\.log\|debugger" dist/ --include="*.html" && echo "⚠️ HTML 中发现调试语句" && exit 1 - 避免直接解析 HTML 字符串做正则匹配——遇到注释、CDATA、模板语法（如
{{#if}}）极易误报；优先用parse5或cheerio类库做真实 DOM 解析
CI/CD 流水线里 HTML 门禁的关键差异
GitHub Actions / Gitea Actions 等 CI 环境不是“增强版本地”，而是独立、干净、无状态的执行单元，所有检查必须显式声明依赖和输入路径。
立即学习“前端免费学习笔记（深入）”；
-
actions/checkout@v4默认不拉取子模块或 LFS 大文件，若 HTML 依赖public/assets/中的图标字体，需额外加fetch-depth: 0或lfs: true - 用
html-validate时，配置文件.htmlvalidate.json必须放在仓库根目录，否则 CI 中会 fallback 到默认规则（可能放过严重问题） - 不要在 CI 中重复 pre-commit 已做的检查（如基础标签闭合），应专注补充：SEO 元信息完整性、HTTP 头响应检查（用
curl -I http://localhost:3000）、首屏关键资源加载顺序验证 - 错误退出码必须明确：CI 脚本里写
html-validate src/*.html || exit 1，不能只写html-validate src/*.html—— 否则即使报错也不会中断流水线
最容易被忽略的是 HTML 文件的“上下文漂移”：同一份 index.html 在本地开发服务器、构建产物、CDN 缓存、微前端子应用中，<base href>、资源路径、环境变量注入方式都不同。门禁规则必须绑定具体构建阶段，而不是笼统地“检查所有 HTML”。
