前端 ReadableStream 分块读取 怎样处理

前端要分块处理网络响应时，先从 response.body 取出 ReadableStreamDefaultReader，再循环调用 read()。关键不是把每个 value 直接转成字符串，而是让 TextDecoder 保留跨分块的 UTF-8 字节，并在流结束时 flush。这样既能边到边显示，也不会因为一个中文字符被拆到两个 chunk 中而乱码。

这篇只讨论浏览器 Fetch 返回的默认可读流：读取、解码、结束、异常和提前取消。ReadableStream 的 getReader() 会锁定流；同一时刻不能再拿第二个 reader，直到当前 reader 释放锁。

先看清分块读取的关系

浏览器拿到的 value 通常是 Uint8Array，它表示“当前到达的一段字节”，不保证对应一个完整的业务行、JSON 对象或中文字符。下面的结构图把响应体、reader、解码器和消费层放在同一条静态关系里，帮助定位每个职责。

用 reader 和 TextDecoder 按块读取

默认 reader 的 read() 每次返回一个 Promise，结果是 { done, value }。当还有数据时 done 为 false；流关闭后变为 true，此时 value 不应再使用。

async function readTextInChunks(response, onChunk) {
  // 没有响应体时，避免对 null 调用 getReader。
  if (!response.body) {
    return;
  }

  const reader = response.body.getReader();
  // stream: true 会保留尚未组成完整字符的 UTF-8 字节。
  const decoder = new TextDecoder("utf-8");

  try {
    while (true) {
      // 每次只取下一段字节，value 的边界由底层流决定。
      const { done, value } = await reader.read();
      if (done) {
        // flush=true 处理最后仍留在解码器中的字节。
        const tail = decoder.decode();
        if (tail) onChunk(tail);
        break;
      }

      const text = decoder.decode(value, { stream: true });
      if (text) onChunk(text);
    }
  } finally {
    // 读取结束或发生异常后释放当前 reader 对流的锁。
    reader.releaseLock();
  }
}

const response = await fetch("/api/stream");
await readTextInChunks(response, (chunk) => {
  // 这里可以追加到 UI 缓冲区，而不是假设 chunk 是完整业务记录。
  output.textContent += chunk;
});

这个函数把“字节流读取”和“业务消费”分开：onChunk 收到的只是可显示文本片段。如果接口协议按换行分隔，还要在外层维护一个字符串缓冲区，找到换行符后再提交完整记录。

为什么不能直接对每个 value 调用 TextDecoder

UTF-8 一个字符可能占多个字节，而网络 chunk 只是传输边界。例如一个字符的前两个字节在本次 read() 返回，剩余字节在下次返回。如果每次都新建解码器，或者不传 { stream: true }，解码器无法记住未完成字符，结果就可能出现替换字符。

可以把图中的“跨块字节缓冲”理解为解码器的责任：调用 decode(value, { stream: true }) 表示后面还会有数据；只在 done 时调用无参数的 decode()，让它完成最后一次 flush。业务层则只处理已经解码出的文本。

结束、异常和提前取消怎么分

正常结束是 read() 返回 done: true；网络故障或底层流出错时，read() 的 Promise 会 reject，应由 catch 或上层错误边界处理。两者都不应该靠“读到空字符串”判断，因为空文本和流结束不是同一个语义。

async function readUntilMatch(response, keyword) {
  if (!response.body) return false;

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  try {
    while (true) {
      // 错误会在 await reader.read() 处抛出，交给调用方决定如何提示。
      const { done, value } = await reader.read();
      if (done) {
        // 正常结束时补齐最后的 UTF-8 片段。
        buffer += decoder.decode();
        return buffer.includes(keyword);
      }

      buffer += decoder.decode(value, { stream: true });
      if (buffer.includes(keyword)) {
        // 已经拿到目标内容，剩余排队数据不再需要。
        await reader.cancel("keyword found");
        return true;
      }

      // 只保留末尾窗口，避免长响应让字符串无限增长。
      if (buffer.length > 4096) buffer = buffer.slice(-2048);
    }
  } finally {
    // releaseLock 只释放锁；cancel 才表示放弃剩余数据。
    reader.releaseLock();
  }
}

try {
  const found = await readUntilMatch(response, "目标片段");
  console.log(found ? "已找到" : "流已结束");
} catch (error) {
  // 真实应用中应把网络错误映射成用户可理解的状态。
  console.error("读取流失败", error);
}

cancel() 和 releaseLock() 作用不同：前者告诉底层“不再需要这条流”，排队数据会被放弃；后者只解除当前 reader 的占用。组件卸载或用户主动停止时通常需要先取消，再释放锁。

常见边界与快速检查

把这四项和接口协议一起确认，基本就能覆盖大多数“ReadableStream 分块读取不对”的问题。特别是 SSE、NDJSON 或自定义文本协议，都应该先解决“chunk 不等于消息”的边界，再决定怎样组装业务数据。

相关问题

ReadableStream 的 value 一定是字符串吗？

不一定。Fetch 响应体的默认读取结果通常是字节数组，需要用 TextDecoder 转换；自定义流也可以 enqueue 其他类型，具体取决于底层源。

什么时候用 getReader({ mode: "byob" })？

只有在处理可读字节流并希望由调用方提供缓冲区时才考虑 BYOB。普通文本响应使用默认 reader 更直接，文章中的分块解码逻辑也更容易保持清晰。

官方参考：https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStream