html-validate必须在构建前运行，而非ci后期补救；动态html结构性缺陷（如p嵌div、table缺tbody）会被浏览器静默修正，导致实际dom与编写dom不一致，仅靠构建阶段校验才能拦截。

html-validate 必须在构建前运行，不是 CI 后期补救工具

动态 HTML 的结构性缺陷（比如 p 里嵌 div、table 缺 tbody、img 自闭合写成 <img> 而非 <img>）根本不会在 JS 运行时报错，而是被浏览器静默修正——你写的 DOM 和实际生成的 DOM 完全不一致。这种偏差只有在构建阶段用 html-validate 拦截才来得及。

常见错误现象：本地开发时 document.querySelector('p').children 返回空数组，但模板里明明写了 <p></p> <div>text</div>

；SSR 页面中 table.tBodies[0] 是 undefined，服务端渲染结构却“看起来正常”。

• VS Code 保存即校验：装 HTMLHint 插件，启用 tag-pair 和 element-permitted-content 规则，比等 CI 报错早至少 5 分钟
• CI 中必须前置执行：npx html-validate src/**/*.html 要放在 vite build 或 webpack 命令之前，失败直接中断，不进产物目录
• element-permitted-content 规则必须自定义：默认配置对 p 标签放行太宽，应显式设为 "p": ["#text", "br", "span", "em"]，否则 <p></p> <div></div> 不会报错

Vite/Webpack 注入逻辑极易污染 HTML 结构

打包插件（如 vite-plugin-html、html-webpack-plugin）不是“把变量塞进去就完事”，它们插入位置一旦越界，就会破坏文档流。典型问题是 <script></script> 被插到 末尾却紧挨着 <main></main> 开头，导致浏览器解析时误判为 内容结束，后续所有节点层级错乱。

使用场景：多页应用、SSR 输出、带环境变量注入的 index.html。

HTML Extract

使用 MinerU 从 HTML 页面和文件中提取内容，将 HTML 转换为保持标题、列表、表格及文本层次结构的干净、结构化 Markdown。F...

下载

• vite-plugin-html 中变量写法必须是 ，写成 %VITE_API_BASE% 会导致字符串残留，变成非法 HTML 文本节点
• Webpack 下 html-loader 处理含 <script type="module"></script> 的片段时，会把 import 当普通字符串，运行时报 ReferenceError: require is not defined
• 多页应用必须为每个页面配独立 HtmlWebpackPlugin 实例，并显式指定 chunks，否则 login 页面可能加载 dashboard 的 JS，触发非预期 DOM 操作

动态插入必须用 insertAdjacentHTML，禁用 innerHTML

innerHTML = htmlStr 是结构断裂的高频源头：它会清空目标元素所有子节点，包括已绑定的事件监听器、已挂载的 Web Component、甚至第三方 SDK 注入的脚本钩子。而 insertAdjacentHTML 只追加或插入，不重置上下文。

性能影响：innerHTML 引发完整子树重建和重排，insertAdjacentHTML 仅触发局部 DOM 更新，实测在列表项频繁更新场景下，FPS 提升 20%+。

• 只允许四种插入位置：'beforebegin'、'afterbegin'、'beforeend'、'afterend'，其中 'beforeend' 最常用，语义等价于 appendChild
• 若需替换而非追加，先调用 el.textContent = '' 清空文本内容（保留事件绑定），再用 insertAdjacentHTML('beforeend', htmlStr)
• 服务端返回的 HTML 字符串若含控制字符（如 \u0000），insertAdjacentHTML 会静默失败，建议前置用 DOMParser 预检：new DOMParser().parseFromString(htmlStr, 'text/html')，检查 doc.body.innerHTML 是否与原始一致

模块化 HTML 片段必须强制包裹根节点

服务端或模板引擎返回的 HTML 片段（如 <p>Hello</p> <div class="meta"></div>）是并列节点，没有共同父级。直接丢给 DOMParser 或 insertAdjacentHTML 会导致部分节点丢失——DOMParser 只保留第一个节点，insertAdjacentHTML 在某些浏览器中会忽略后续节点。

容易踩的坑：一个模块导出 generateCardHtml(user)，另一个模块直接 el.insertAdjacentHTML('beforeend', A.generateCardHtml())，结果卡片只渲染了标题，元信息消失。

• 所有模块内 HTML 字符串生成函数，必须强制包裹一层根节点：<div>${htmlStr}</div>，确保解析后有唯一 body.children[0]
• 若需保持原有语义结构（如卡片本该是 <article></article>），则包裹节点应为语义等价容器：<article>${htmlStr}</article>，而非无意义的 <div> <li>ES 模块内禁止跨模块隐式传递 HTML 字符串；应导出 <code>renderCard(el, user)，内部完成包裹 + 解析 + 插入，把 DOM 操作封闭在模块边界内
真实问题往往藏在“看着正常”的地方：缩进对齐的 <p></p> <div></div> 在 Elements 面板里是三个同级节点；innerHTML 替换后事件监听器莫名失效；多页应用里某个页面突然加载了不该有的 JS。这些都不是运行时能靠 try-catch 捕获的错误，而是编译链路里没卡住的结构性断点。