网关层需用流式tokenizer（如htmlparser2）绕过dom构建解析大html，禁用xmlmode，注入chunk-meta注释保留上下文，控制writablestream的highwatermark与drain机制防内存堆积，且分块逻辑不可下放到cdn边缘。
网关层对HTML大文档的流式解析必须绕过DOM构建
直接用 new DOMParser() 或服务端 jsdom 加载 50MB HTML 会触发 V8 内存暴涨甚至 OOM，网关层根本扛不住。高性能网关不负责渲染，只做结构识别与分块路由——这意味着必须跳过完整 DOM 树构建，改用流式 tokenizer（如 htmlparser2 的 WritableStream）边读边切。
常见错误现象：RangeError: Maximum call stack size exceeded 出现在解析含千级嵌套 <div> 的老系统导出页时，本质是递归下降解析器栈溢出；换成 <code>htmlparser2.Parser + 自定义 cbs 回调，仅监听 opentag 和 closetag 事件，内存占用可压到 10MB 以内。
- 禁用
xmlMode: true，HTML 文档用xmlMode: false（否则对自闭合标签如<img>解析失败） - 不要在
text回调里拼接全文本——用Buffer或Uint8Array流式暂存，按需截断 - 若需保留语义层级（如识别
<h2></h2>下所有段落），在opentag中记录栈深度，closetag时弹出，避免深递归
按语义块切分后必须带上下文锚点再转发
网关把一个 30MB 的帮助文档切成 200 个 <section></section> 块后，如果直接发给下游服务，对方无法还原原始位置——比如用户点击了第 17 个 <h3 id="api-auth"></h3> 锚点，但下游只收到无 ID 的纯 HTML 片段，跳转就失效。
解决方案是在每个切片前注入轻量元数据，例如：
<!-- chunk-meta: { "src": "help.html", "offset": 12480, "headers": ["h1", "h2", "h3"], "id": "api-auth" } -->
<h3 id="api-auth">认证流程</h3>
<p>使用 OAuth2.0 ...</p>
- 元数据用 HTML 注释包裹，确保不干扰下游 CSS/JS 执行
-
offset字段让下游能反查原始文件偏移，用于日志定位或调试 - 若下游是 SSR 服务，可提取
id构建客户端跳转链接；若是向量化服务，headers数组直接喂给 embedding 模型作为上下文提示
流式分发时需控制 chunk 大小与缓冲策略
网关不是中转站，而是流量调节阀。把 50MB HTML 拆成 64KB 块直接 pipe() 给下游，可能因下游消费慢导致网关内存堆积——尤其当后端是 Java Spring Boot（默认 servlet 容器缓冲区仅 8KB）时，未及时读取的 chunk 会滞留在 Node.js Writable 内部缓冲区。
关键参数必须显式设置：
-
highWaterMark: 65536（64KB）：控制每个WritableStream缓冲上限 - 下游响应
drain事件后才继续 push 新 chunk，不能无脑 write - 超时强制中断：对单个 chunk 设置
setTimeout，超过 3s 未被消费则destroy()当前流并上报告警
注意：Node.js stream.Writable 默认 objectMode: false，传入字符串必须指定 encoding='utf8'，否则中文会乱码；若用 Buffer，务必确认下游是否支持二进制接收。
CDN 边缘节点无法处理动态 HTML 分块
别指望 Cloudflare Workers 或阿里云 CDN 边缘脚本去运行 htmlparser2 ——它们限制 CPU 时间（通常 ≤ 50ms）、禁止动态 require、不支持 stream API。所有 HTML 流式重组必须落在网关层（即你可控的 Node.js 或 Rust 实例），而非边缘。
真实部署中容易被忽略的一点：网关和下游服务之间的 HTTP 协议版本。若网关用 HTTP/1.1 分块传输（Transfer-Encoding: chunked），而下游是 HTTP/2 服务且未正确处理流式 body，会导致第一个 chunk 后连接静默关闭。验证方式是用 curl -v 看响应头是否含 content-length；若为空且无 transfer-encoding，说明下游提前结束了流。
