核心解法是语义结构切片+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></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></p>所属的标题路径（如用于导航锚点或侧边大纲），加return_each_element=True - 含
<table> 或 <code><pre class="brush:php;toolbar:false;"><code></code> 的页面，换用 <code>HTMLSemanticPreservingSplitter</code>，否则表格跨行、代码缩进会被截断 <h3> <code><template></template></code> 内容不 clone 就用必静默失败</h3> <p><code><template></template></code> 的 <code>content</code> 是只读 <code>DocumentFragment</code>，直接 <code>appendChild(template.content)</code> 会把内容“搬走”，第二次调用返回空 Fragment——控制台无报错，但后续所有渲染都失效，极难定位。</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5806" title="html-deploy"><img src="https://img.php.cn/upload/skill/000/000/081/179066538882434.jpg" alt="html-deploy" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="overflowclass">html-deploy</a> <p class="overflowclass">使用 htmlcode.fun 将 HTML 内容或文件部署到网页，适用于用户要求“部署到网页”“托管此 HTML”“生成此前端...的实时链接”等场景。</p> </div> <a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div> </pre> <ul> <li>必须用 <code>template.content.cloneNode(true)或document.importNode(template.content, true) -
cloneNode(true)不保留事件监听器和data-状态，查子元素前先克隆再querySelector -
<template></template>里的<script></script>和<style></style>全被忽略，别指望它自动执行或生效 - ID 冲突要主动处理：克隆后若存在重复
id="modal-close"，document.getElementById只取第一个
非首屏内容必须用 <template></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>） <li>表格动态行务必 append 到已有 <code><tbody>，别替换整个 <code><table> <li>批量插入多个节点时，先塞进 <code>DocumentFragment，再一次性appendChild，避免反复触发 layout
hydration 边界没接管会导致状态丢失
如果页面是 SSR 输出的（比如 Next.js / Nuxt 首屏），又用 <template></template> 补充后续内容，ID、data-state、表单焦点这些不会自动同步。用户滚动到新模块后点击按钮没反应、输入框光标消失，大概率是这个原因。
最易被忽略的是：你写了完美的切片逻辑和 IntersectionObserver 加载，却忘了在克隆后手动恢复表单值、重绑事件、或重置 aria-expanded 等可访问性状态。这里没有银弹，每类交互组件都需要显式 hydration 接管。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
