html-validate 是生产环境 HTML 质量的第一道闸口，因其可集成 CI/CD、支持自定义规则、能在 PR 阶段自动拦截、输出机器可读格式，且校验源码而非仅终产物，远超 W3C 在线工具能力。
直接用 html-validate 做 CI/CD 自动化校验，比在线工具更可靠、可配置、能拦截上线。 它不是“补充手段”，而是生产环境 HTML 质量的第一道闸口。
为什么不能只靠 W3C 在线校验
W3C 工具（如 validator.w3.org/nu）适合人工抽查，但无法集成进开发流程：它不支持批量扫描、不能自定义规则粒度、无法在 PR 阶段自动失败、也不输出机器可读格式供脚本解析。更重要的是，它校验的是“最终产物”，而你真正需要控制的是源码阶段的规范性——比如禁止开发者写 
alt，而不是等构建完再提醒。
常见误判场景包括：
-
v-if、x-data等框架指令被标为“unknown attribute”，这不是错误，是校验器不认识——但你得明确告诉工具哪些属性可忽略 - 本地
file://路径下验证通过，上线后因路径拼接或构建插件注入导致实际失效，校验器完全不报 -
innerHTML = "这类 JS 动态插入内容，校验器根本看不到xxx"
html-validate 的核心配置要点
它基于 Node.js，规则高度可编程，关键在于配置文件是否覆盖真实风险点。默认推荐规则太宽松，必须手动收紧：
- 强制所有
alt："img-req-alt": true，同时禁用空 alt 的冗余写法："img-redundant-alt": true - 禁止内联样式：
"no-inline-style": true，避免结构与表现耦合 - 限制标题层级：
"heading-required": { "max-depth": 1 }，确保每个页面只有一个 - 排除构建目录：
"files": ["src/**/*.html", "!dist/**", "!build/**"]，只校验源码 - 启用语义检查：
"head-valid-content-model": true，防止<script></script>错放在外
配置示例（.htmlvalidate.json）：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
{
"root": true,
"extends": ["html-validate:recommended"],
"rules": {
"img-req-alt": true,
"img-redundant-alt": true,
"no-inline-style": true,
"heading-required": { "max-depth": 1 },
"head-valid-content-model": true
},
"files": ["src/**/*.html", "!dist/**", "!build/**"]
}
CI 中如何真正起效
光装工具没用，得让它在代码合并前卡住问题。典型做法：
- 在 GitHub Actions 或 GitLab CI 中添加步骤：
npx html-validate --config .htmlvalidate.json src/**/*.html - 确保退出码非 0 时流水线中断——
html-validate默认就满足这点，无需额外包装 - 配合 lint-staged，在 pre-commit 阶段跑：
"precommit": "lint-staged"+"*.html": ["html-validate --fix"]，自动修复基础问题（如引号、大小写） - 若项目含 Pug/Vue/JSX，需额外配置语言服务器（如
volar或pug-lsp），否则校验器只处理纯.html文件
注意：html-validate 不校验路径有效性、CSP 策略、服务端模板语法（如 ），这些要靠其他工具链补位。
容易被忽略的边界情况
很多团队配完就以为万事大吉，结果发现某些错误始终漏掉：
-
缺少引号 → 校验器报Attribute value must be quoted，但若写成就合法；浏览器能容错，校验器不放过 - 末尾空格 → 某些模式下触发警告，但不影响渲染，是否禁用取决于团队规范
- 使用了实验性 HTML 属性（如
inert）→ 需手动启用对应插件，否则默认报错- 自定义元素（如
"html-custom-data": ["./custom-elements.json"]最常被跳过的动作是：没在构建产物上做终验。即使 CI 通过，也该在
dist/index.html上再跑一次html-validate，确认打包插件没注入非法结构（比如重复或错位<script></script>）。这步不能省，因为框架 SSR 输出、HTML 插件注入、CDN 重写都可能悄悄破坏结构。 - 使用了实验性 HTML 属性（如
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
