核心解法是语义结构切片+template按需注入；必须显式配置headers_to_split_on为h1–h3三级，启用return_each_element=True保留标题路径；含表格或代码时改用HTMLSemanticPreservingSplitter；克隆template.content须用cloneNode(true)或importNode；非首屏内容禁用display:none而用template；SSR场景下需手动hydration接管状态。
超长 HTML 文档（比如百万字技术文档、长图文新闻页）直接整页加载会触发 OOM、卡死主线程、首屏白屏超 5s——这不是 JS 写得烂，而是浏览器解析和渲染路径本身被撑爆了。核心解法不是“压缩 HTML”，而是用语义结构切片 + <template> 按需注入，把 DOM 构建压力从一次性扛住，变成按视口节奏分摊。
HTMLHeaderTextSplitter 必须显式配 headers_to_split_on
默认只按 h1 切，但门户网站/技术文档普遍是 h1–h3 三级嵌套。漏掉任意一级，对应层级就全吞进上一块里，常见现象是单块超 500KB、向量化失败、或 document.createElement('template') 克隆时报错 RangeError: Maximum call stack size exceeded。
- 必须传
headers_to_split_on=[("h1", "title"), ("h2", "section"), ("h3", "subsection")] - 若需保留每个
<p>所属的标题路径（如用于导航锚点或侧边大纲），加return_each_element=True - 含
<table>或<pre><code>的页面，换用HTMLSemanticPreservingSplitter，否则表格跨行、代码缩进会被截断
<template> 内容不 clone 就用必静默失败
<template> 的 content 是只读 DocumentFragment，直接 appendChild(template.content) 会把内容“搬走”，第二次调用返回空 Fragment——控制台无报错，但后续所有渲染都失效，极难定位。
- 必须用
template.content.cloneNode(true)或document.importNode(template.content, true) -
cloneNode(true)不保留事件监听器和data-状态，查子元素前先克隆再querySelector -
<template>里的<script>和<style>全被忽略，别指望它自动执行或生效 - ID 冲突要主动处理：克隆后若存在重复
id="modal-close"，document.getElementById只取第一个
非首屏内容必须用 <template> 而非 display: none
display: none 的区块仍参与 DOM 构建和 CSSOM 计算，只是不绘制；对商品列表页后 500 条、长图文下半截，这会让首屏解析耗时翻倍，实测可拖慢 300–800ms。
立即学习“前端免费学习笔记（深入）”；
- 服务端返回的 HTML 片段，先塞进临时
template：const tmp = document.createElement('template'); tmp.innerHTML = htmlStr; - 取
tmp.content.cloneNode(true)，确保标签自动修正（比如补全缺失的<tbody>） - 表格动态行务必 append 到已有
<tbody>，别替换整个<table> - 批量插入多个节点时，先塞进
DocumentFragment，再一次性appendChild，避免反复触发 layout
hydration 边界没接管会导致状态丢失
如果页面是 SSR 输出的（比如 Next.js / Nuxt 首屏），又用 <template> 补充后续内容，ID、data-state、表单焦点这些不会自动同步。用户滚动到新模块后点击按钮没反应、输入框光标消失，大概率是这个原因。
最易被忽略的是：你写了完美的切片逻辑和 IntersectionObserver 加载，却忘了在克隆后手动恢复表单值、重绑事件、或重置 aria-expanded 等可访问性状态。这里没有银弹，每类交互组件都需要显式 hydration 接管。
