校验必须跑在构建产物上而非 src 目录，因模板语法会在构建后被移除；ci 中需确保 build 完成后再校验 dist/ 下文件，并用 html-validate 替代 w3c 验证器以支持自动化集成与规则统一管理。
校验必须跑在构建产物上，不是 src 目录
本地 src/index.html 里有 {{ title }}、v-if、x-on:click 这类模板语法或框架指令，W3C 验证器或 html-validate 会直接报错，但这不是你该修的代码——它们会在构建后被移除或转译。真正要校验的是 dist/index.html 或 build/index.html。
常见踩坑点：
- CI 流程里没等
npm run build完成就执行npx html-validate dist/**/*.html，导致校验空目录或旧文件 - Webpack 的
html-webpack-plugin注入了动态变量（如<meta name="version" content="<%= htmlWebpackPlugin.options.env.VERSION %>">），若构建时未传环境变量，产出 HTML 会含非法占位符，校验失败 - 使用 Vite 时，
base配置影响资源路径，但校验器不关心路径是否可达，只检查语法；不过若dist未正确生成（比如开发模式下直接校验），会误判为文件缺失
用 html-validate 替代 W3C 在 CI 中落地
html-validate 是 Node.js 工具，支持规则配置、退出码控制、SARIF 输出，比在线验证器更适合分布式团队自动化集成。W3C validator.w3.org/nu/ 无法嵌入 pipeline，也不支持自定义规则屏蔽误报。
实操建议：
- 安装：
npm install --save-dev html-validate - 配置
.htmlvalidate.json，例如强制双引号、禁用内联样式、要求alt属性：{ "rules": { "attribute-quotes": "error", "no-inline-style": "warn", "img-requires-alt": "error" } } - CI 中加一步：
npx html-validate dist/**/*.html --format stylish --max-warnings 0，设--max-warnings 0可让警告也触发失败（适合强约束场景） - 避免全局安装，防止不同项目 Node 版本或规则冲突
多仓库共用同一套校验规则怎么管理
分散在各 repo 的 .htmlvalidate.json 很难同步更新。推荐把规则抽成独立 npm 包，比如 @team/html-validate-config，内容仅为导出规则对象：
module.exports = {
"rules": {
"attr-lowercase": "error",
"id-unique": "error",
"head-title": "error"
}
};
各项目安装：npm install --save-dev @team/html-validate-config，然后在自己项目的 .htmlvalidate.json 中引用：
{
"extends": "@team/html-validate-config"
}
这样规则升级只需发一个 patch 版本，所有项目 npm update 即可生效。注意：extends 不支持相对路径跨仓库引用，必须走 npm registry。
修复阶段别依赖人工，优先自动补全
校验发现的问题中，约 60% 属于可安全自动修复的类型：缺闭合标签、属性值漏引号、布尔属性冗余赋值等。手动改既慢又易漏。
html-validate 本身不带修复能力，但可搭配 prettier + 自定义脚本：
-
prettier对 HTML 支持良好，配置"htmlWhitespaceSensitivity": "ignore"避免破坏换行语义 - 写一个简单脚本，对
dist/**/*.html执行prettier --write，再跑校验；CI 中可设为「修复并重验」两阶段 - 慎用全自动修复：比如
<img src="logo.png">→<img src="logo.png">安全，但<div class="a" b> → <code><div class="a b"> 可能改变 CSS 选择器匹配逻辑（若原样式写的是 <code>div[class~="a"]）跨库协作最易被忽略的点：校验规则和修复行为必须版本锁定。哪怕只是小版本升级，
html-validate@4.2.0和@4.3.0对template标签的处理可能不同，导致某仓库突然失败。所有团队共享的 config 包，应明确 peerDependencies 并在 CI 中校验工具版本一致性。
