不能靠 import './header.html' 实现 HTML 模块化，浏览器会报 TypeError；HTML 模块化本质是 JS 控制结构复用，需拆清加载、解析、挂载三环节，fetch + DocumentFragment 是最轻量可靠方案，Web Components 是唯一原生封装方案，开发必须起本地服务。
不能靠 import './header.html' 实现 HTML 模块化，浏览器会直接报 TypeError: Failed to resolve module specifier；所谓“HTML 模块化”本质是 JS 层控制结构复用，异步组件必须把 HTML 片段加载、解析、挂载三个环节拆清楚，否则容易卡顿、白屏或事件丢失。
fetch + DocumentFragment 是最轻量可靠的异步插入方案
直接写 el.innerHTML = await fetch('nav.html').then(r => r.text()) 看似简单，但会触发多次 layout，尤其在列表类组件中性能崩坏。DocumentFragment 把所有节点先组装好再一次性挂载，是唯一能压平重排次数的确定性手段。
- 必须在
fetch返回文本后**立刻**创建 fragment：const frag = document.createDocumentFragment() - 逐个
appendChild到 fragment，**不是**先存数组再批量 append —— 后者仍是 N 次 DOM 插入 - 最后统一
container.appendChild(frag)，且建议包一层requestAnimationFrame对齐渲染帧 - 别对 fragment 调用
innerHTML—— 它不支持该属性，会静默失败
Web Components 是唯一真正封装 HTML/CSS/JS 的原生方案
如果你需要样式隔离、属性响应、生命周期管理，customElements.define() 不是可选项，而是必要路径。但它不是“写完就能用”，漏掉关键约束会立即报错。
- 标签名必须含短横线（如
<site-header>），否则注册失败 -
constructor里必须调用super()，否则构造失败并报Failed to construct 'CustomElement' - DOM 操作只能在
connectedCallback中进行，constructor里操作会取到空this.shadowRoot - 想监听属性变化，得同时声明
static get observedAttributes()和attributeChangedCallback，缺一不可
template 标签 + JS 克隆适合无构建依赖的轻量复用
不需要服务器、不依赖打包工具、IE11 也支持，但容易踩坑：克隆方式不对会导致表单元素状态丢失、事件绑定失效。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 用
document.importNode(template.content, true)替代cloneNode(true)，前者能正确复制<input>的当前值和事件监听器 - 克隆后记得用
document.getElementById('xxx').appendChild(imported)，别漏掉挂载动作 - 如果模板里有
<slot>，需确保父容器有对应内容，否则 slot 渲染为空 - 不要在克隆前读取容器尺寸（如
offsetHeight），这会强制浏览器 flush layout，让 fragment 失效
开发时必须起本地服务，file:// 协议下模块全挂
哪怕只写了 <script type="module" src="main.js"></script>，Chrome/Firefox 也会因 CORS 拒绝加载任何模块资源 —— 包括 fetch('header.html')。这不是 bug，是安全策略。
- 推荐用
npx serve或python3 -m http.server，端口默认即可 - Vite 用户无需额外配置，
vite命令自带服务，且自动处理.html片段 import（需配合插件如vite-plugin-html） - Webpack 用户若用
html-loader，注意它只在构建期生效，开发时仍要走 HTTP 服务加载
异步组件真正的复杂点不在“怎么加载”，而在于“什么时候插入才不影响用户操作”——数据就绪、节点建完、fragment 组装完成，这三个动作必须严格串行；任何一步提前或滞后，都会导致 layout 抖动、事件丢失或首屏空白。这不是可以靠加个 async 就解决的问题。
