html-validate必须在构建前运行，而非CI后期补救；动态HTML结构性缺陷（如p嵌div、table缺tbody）会被浏览器静默修正，导致实际DOM与编写DOM不一致，仅靠构建阶段校验才能拦截。
html-validate 必须在构建前运行，不是 CI 后期补救工具
动态 HTML 的结构性缺陷（比如 p 里嵌 div、table 缺 tbody、img 自闭合写成 <img alt="从底层编译着手解决前端动态HTML代码质量缺陷的防护实践" > 而非 <img alt="从底层编译着手解决前端动态HTML代码质量缺陷的防护实践" >）根本不会在 JS 运行时报错，而是被浏览器静默修正——你写的 DOM 和实际生成的 DOM 完全不一致。这种偏差只有在构建阶段用 html-validate 拦截才来得及。
常见错误现象：本地开发时 document.querySelector('p').children 返回空数组，但模板里明明写了 <p></p>
<div>text</div>
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。
-
vite-plugin-html中变量写法必须是<%= VITE_API_BASE %>，写成%VITE_API_BASE%会导致字符串残留，变成非法 HTML 文本节点 - Webpack 下
html-loader处理含<script type="module">的片段时，会把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>${htmlStr}</article>，而非无意义的<div> - ES 模块内禁止跨模块隐式传递 HTML 字符串；应导出
renderCard(el, user)，内部完成包裹 + 解析 + 插入，把 DOM 操作封闭在模块边界内
<p></p>
<div></div> 在 Elements 面板里是三个同级节点；innerHTML 替换后事件监听器莫名失效；多页应用里某个页面突然加载了不该有的 JS。这些都不是运行时能靠 try-catch 捕获的错误，而是编译链路里没卡住的结构性断点。 
