HTMLHint 配置必须覆盖动态加载的碎片文件，如 header.html、nav.html 等，否则未闭合标签或缺失 alt 会在运行时破坏 DOM 结构；需将碎片路径加入 glob 模式、CI 中校验、构建时解析校验、强制 BEM 命名、服务端缓存前剥离用户态标记。
HTMLHint 配置必须覆盖动态加载的片段
很多项目只对入口 index.html 运行 htmlhint，却忽略通过 fetch() 加载的 header.html、nav.html 等碎片文件——这些文件一旦存在未闭合标签或缺失 alt，就会在运行时破坏结构，且无法被构建流程捕获。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 把所有碎片路径加入
htmlhint的 glob 模式，例如：htmlhint "**/*.html" --config .htmlhintrc - 在 CI 流程中增加检查步骤，确保
fragments/目录下所有 HTML 文件都通过验证 - 若使用 Vite，可通过
vite-plugin-html或自定义插件，在构建时读取并校验碎片内容 - 注意：
innerHTML注入的字符串不会被 HTMLHint 扫描，必须确保源文件（如sidebar.html）本身合规
fragment 拼接前必须做基础结构校验
用 document.createDocumentFragment() 提升插入性能没错，但若碎片 HTML 本身含嵌套错误（比如 <p></p> 里套 <div>），浏览器会静默修正 DOM 树，导致最终结构与预期不符，尤其影响 CSS 选择器和 JS 查询逻辑。<p>实操建议：</p>
<p><span>立即学习</span>“<a href="https://pan.quark.cn/s/cb6835dc7db1" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">前端免费学习笔记（深入）</a>”；</p>
<ul>
<li>在 <code>fetch().then(html => {...}) 后、创建 fragment 前，先用 new DOMParser().parseFromString(html, 'text/html') 解析并检查 parser.errors（需 polyfill 或仅用于开发环境）
<body> 或 <head> 标签——碎片应只含片段级内容，如 <header>...</header>
frag.appendChild(div) 后再 appendChild 到页面；先验证 div.children.length > 0，防止空 fragment 导致布局塌陷class 命名冲突是碎片化最隐蔽的质量漏洞
多个团队各自维护 card.html、list.html，都用 class="title"，合并后样式互相覆盖，调试时发现改了 A 组件的 .title 却影响了 B 组件的排版——这不是 CSS 问题，是 HTML 结构层契约失效。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 强制所有碎片外层容器带唯一前缀，如
<div class="cmp-product-card">，子元素严格用 BEM：cmp-product-card__title、cmp-product-card__price - 禁止碎片内使用全局语义类（如
text-center、hidden），这类工具类应由宿主页面统一注入，碎片只负责结构 - 构建时可用正则扫描所有碎片文件，报错提示 “found class='title' outside BEM pattern”
- 若用 Web Components，
:host样式隔离不解决 HTML 层命名污染，仍需前置约束
服务端缓存碎片时必须剥离用户态标记
SSR 输出的 footer.html 若含 <span>欢迎，{{user.name}}</span>，却被 CDN 缓存为静态内容，结果张三看到李四的名字——这种错误不会出现在本地开发，只在上线后随机爆发。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 所有碎片模板必须显式声明是否可缓存：在文件顶部加注释
<!-- @cacheable: false -->，构建工具据此跳过缓存逻辑 - 可缓存碎片中禁止出现任何模板变量（
{{ }}、$user、req.session），只允许纯静态 HTML + 占位注释如<!-- USER_NAME --> - 缓存 key 必须包含请求上下文签名，例如
footer:zh-CN:desktop:guest，而非简单哈希文件路径 - CDN 上禁用
/fragments/*.html路径的自动缓存，改由服务端响应头精确控制：Cache-Control: public, max-age=3600仅对真正静态的碎片生效
真正容易被忽略的是：HTML 质量碎片化不是单点工具能解决的问题，它发生在构建、部署、运行三个环节的交界处——一个没被 htmlhint 扫到的 nav.html，可能让整个首屏的无障碍阅读器失效；一段没加前缀的 class="modal"，会在微前端聚合时让两个弹窗逻辑互相劫持。
