HTML Fetch 流式响应读取指南

本文深入解析了 HTML Fetch API 中流式响应读取的核心机制与实战难点，指出 response.body 作为 ReadableStream 必须通过 getReader() 和循环 read() 手动处理，而 text()/json() 等便捷方法会锁死流、阻塞内存，完全不适用于 SSE、大模型 token 流或分块文件等实时场景；文章重点揭示了 UTF-8 多字节字符截断风险（需 TextDecoder 配置 stream: true）、跨 chunk 换行解析的缓冲策略，以及浏览器原生缺乏行迭代支持的现实困境，并直击流式开发中真正棘手的工程问题——错误恢复、语义完整性保障和 UI 渲染节流，强调所有这些都需开发者自主兜底，而非依赖框架或浏览器“开箱即用”。

Fetch 的 response.body 确实是 ReadableStream，但直接读取流式响应需要手动处理 getReader() 和 read() 循环，不是开箱即用的“自动逐行输出”。

为什么 response.text() 或 response.json() 不能流式处理

这两个方法会等待整个响应体下载完成再解析，内部调用了 arrayBuffer()，完全阻塞流。一旦调用，response.body 就被锁死，后续无法再调用 getReader()。

• 常见错误现象：TypeError: Failed to execute 'getReader' on 'ReadableStream': ReadableStream is locked
• 使用场景：服务端返回 SSE（Server-Sent Events）、LLM 流式 token、大文件分块传输等需要边收边处理的场景
• 关键判断：必须在拿到 Response 后立刻操作 response.body，且只做一次 getReader()

如何正确读取 ReadableStream 并按 chunk 处理

核心是用 reader.read() 返回的 Promise 解析每次接收的 { done, value }，其中 value 是 Uint8Array，需手动转字符串（注意编码）。

• 不要直接 new TextDecoder().decode(chunk) —— 这会截断 UTF-8 多字节字符（如中文），应传入 { stream: true } 选项
• 推荐写法：const decoder = new TextDecoder("utf-8", { stream: true });，然后循环中调用 decoder.decode(chunk, { stream: true })
• 示例片段：

const response = await fetch("/api/stream");
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8", { stream: true });

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value, { stream: true });
  console.log(text); // 每次收到的 chunk 字符串
}

如何模拟“逐行”处理（比如 SSE 或换行分隔的流）

浏览器原生不提供 for await...of 对 response.body 的行迭代支持（Chrome 117+ 实验性支持 response.body.pipeThrough(new TextDecoderStream()).pipeThrough(new TransformStream(...))，但兼容性差）。稳妥做法是手动拼接 + 换行符切分。

• 维护一个 buffer = ""，每次将 decoder.decode(value) 的结果追加进去
• 用 buffer.split("\n") 提取完整行，保留最后一段未闭合的（可能跨 chunk）作为新 buffer
• 注意处理 \r\n 和 \n 两种换行；SSE 场景还需识别 data:、event: 前缀
• 性能影响：短 chunk 频繁触发 split 可能有开销，但比等全量响应低得多

流式读取真正的复杂点不在语法，而在于错误恢复（网络中断后是否重连）、chunk 边界语义（比如 JSON 分片怎么保证不割裂对象）、以及 UI 渲染节奏控制（避免高频 innerHTML += 导致卡顿）。这些都得自己兜底，浏览器不会替你管。

今天关于《HTML Fetch 流式响应读取指南》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！