html-validate 不能直接塞进 webpack/vite 构建脚本，因其是静态扫描工具，而构建工具在生成最终 html 前无法校验动态注入内容；若校验源模板则缺失运行时结构，若校验 dist 文件则错误已固化，必须在 html 字符串生成后、写入磁盘前介入，如通过 vite-plugin-html 的 transformhtml 钩子或 webpack 的 compilation.hooks.htmlwebpackpluginalterassettags。
html-validate 为什么不能直接塞进 webpack/vite 构建脚本里
因为 html-validate 是静态扫描工具，而打包工具（如 webpack/vite）在构建阶段才生成最终 HTML——如果校验对象是 src/index.html 这类源模板，它根本没包含动态注入的 <script></script>、<link> 或服务端变量；如果等 dist/index.html 写完再扫，问题已固化，修复要回溯两层逻辑（模板 + 构建配置）。
真正有效的介入点，是在 HTML 字符串生成后、写入磁盘前。比如 vite-plugin-html 的 transformHtml 钩子、webpack 的 compilation.hooks.emit，或者 eleventy/astro 的 onBuildEnd 后立即调用校验 API。
- 不要用
npx html-validate dist/**/*.html放在build命令之后——此时文件已落地，错误定位难，且 CI 中可能因缓存跳过 - 推荐用编程式调用：
htmlValidate.validate(htmlString, { config: './.htmlvalidate.json' })，传入内存中刚生成的 HTML 字符串 - 若用
html-webpack-plugin，需监听compilation.hooks.htmlWebpackPluginAlterAssetTags，而非done，否则 script 标签顺序还没确定
如何让 html-validate 规则适配不同构建产物路径
团队项目往往有多个 HTML 入口：SPA 的 public/index.html、SSR 的 src/templates/app.html、微前端子应用的 src/mfe/portal.html。硬写 src/**/*.html 会漏掉 public 目录，扫 **/*.html 又会误报 node_modules 里的 demo 文件。
解决方案不是靠 glob 猜路径，而是把路径识别逻辑下沉到校验入口：CLI 工具启动时读取项目类型（通过 package.json 中是否存在 "type": "module" 或 vite.config.js），再映射出对应 HTML 模板根目录。
- SPA 项目默认扫描
public/**/*.html和src/**/*.html（含 Vue/React 模板中的<template></template>片段） - SSR 项目优先扫描
src/templates/**/*.{html,ejs,handlebars}，并跳过dist/server/ - 微前端项目加一层
--mfe开关，自动启用ignore: ["src/mfe/*/index.html"]并关闭document-title-missing
CI 中 html-validate 报错但本地不报，怎么快速对齐
最常见原因是解析器版本差异：html-validate 依赖 parse5，而 v7.1.0+ 对自闭合标签（如 <img>）的处理更严格；CI 使用的是缓存 node_modules，本地装的是最新版，或反之。
另一个隐形陷阱是换行符：\r\n（Windows）和 \n（Linux/macOS）会导致同一段 HTML 在不同环境被解析成不同 AST 节点，进而触发或跳过 attr-no-duplication 类规则。
- 强制统一解析器版本：在
.htmlvalidate.json中显式指定"parserOptions": { "xmlMode": false }，避免依赖底层自动推断 - CI 中加一步
sed -i 's/\r$//' $(find . -name "*.html" -type f)统一换行符（仅限 Linux runner） - 本地开发用 VS Code 插件
EditorConfig统一设置end_of_line = lf，比靠 CLI 临时修复更可靠
打包阶段校验失败，该阻断构建还是只警告
答案取决于错误类型。结构性错误（如 p 里嵌 div、table 缺 tbody）必须阻断——浏览器静默修正后，JS 获取的 DOM 结构与源码不一致，document.querySelector('p').children 返回空数组就是典型信号；而语义类警告（如 heading-level 跳级、attr-req-title 缺失）可设为 warning，只上报不中断。
关键不是全开 --max-warnings 0，而是按规则分级：
- 硬性失败规则（CI 中 exit code ≠ 0）：
attr-req-alt、id-unique、element-permitted-content - 软性警告规则（本地开发提示，CI 不阻断）：
attr-lowercase、head-title、attr-req-lang - 完全禁用规则（避免干扰）：
doctype-first（SSR 场景下无法保证）、inline-script（现代项目基本不用内联 JS）
别把“所有规则都必须 fail”当成质量红线——真正影响交付的是那些会让 DOM 行为失控的结构性缺陷，而不是格式或风格问题。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
