JavaScript TextDecoderStream 怎样把流式字节转换成文本

处理流式响应时，拿到的往往不是一段完整字符串，而是不断到达的 Uint8Array 分块。直接对每个分块调用 TextDecoder.decode()，容易把跨分块的 UTF-8 字符处理错；更稳妥的方式是把字节流接入 TextDecoderStream，让解码器维护跨块状态，再逐段消费文本。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream

可以先记住一条主线：ReadableStream → pipeThrough(new TextDecoderStream()) → ReadableStream。TextDecoderStream 只做编码转换，换行拆分、JSON 解析和业务事件识别仍由后面的代码负责。

先确认字节流与文本流的边界

TextDecoderStream 是 Encoding API 的流式版本，形状类似 TransformStream，输入端接收字节，输出端产生字符串。它适合 fetch 响应体、文件流或自定义 ReadableStream；它不会替你判断一段文本是不是 JSON，也不会自动按换行切出完整业务消息。

因此，设计时把职责拆成两层：解码器处理字节边界，业务消费者处理文本边界。这样即使一个中文字符被拆在两个网络分块中，也不会要求业务层自己拼接字节。

用 pipeThrough 接上解码器

最小连接方式是把响应体传给 pipeThrough()，返回的流可以用 for await...of 持续读取。下面的例子把每个文本片段追加到页面容器；示例中的片段不保证对应完整的一行或完整 JSON。

async function readTextStream(response, output) {
  // response.body 是字节流；没有响应体时直接结束，避免对 null 调用 pipeThrough。
  if (!response.body) return;

  // TextDecoderStream 负责跨分块解码，业务层只接收字符串片段。
  const textStream = response.body.pipeThrough(new TextDecoderStream("utf-8"));
  for await (const chunk of textStream) {
    // chunk 可能只是半行文本，按业务协议决定后续是否继续缓存。
    output.textContent += chunk;
  }
}

如果输入不是 fetch，也可以把任意产生 Uint8Array 的 ReadableStream 接到同一条管道。关键不是输入来源，而是让字节流只经过一个负责编码边界的解码器。

处理分块和编码参数

构造函数可以指定编码，默认常见场景使用 UTF-8。解码器会把不完整的多字节序列留到后续分块继续处理，所以不要在业务层按“每个 chunk 都是完整字符”来截断或统计。若协议还要按换行消费，可以再加一层文本缓存。

async function readLines(byteStream, onLine) {
  // 先把字节流变成文本流，避免按字节分块误切 UTF-8 字符。
  const textStream = byteStream.pipeThrough(
    new TextDecoderStream("utf-8", { fatal: true, ignoreBOM: false })
  );
  let pending = "";

  for await (const chunk of textStream) {
    // pending 保存跨分块的半行，换行出现后才交给业务回调。
    pending += chunk;
    const lines = pending.split("\n");
    pending = lines.pop() ?? "";
    for (const line of lines) {
      if (line.trim() !== "") await onLine(line.replace(/\r$/, ""));
    }
  }

  // 流结束时处理最后一行，即使它没有以换行符结尾。
  if (pending.trim() !== "") await onLine(pending.replace(/\r$/, ""));
}

fatal: true 表示遇到无法解码的字节时抛出异常，适合编码必须严格正确的协议；默认的非 fatal 模式会用替换字符继续输出，适合允许降级展示的文本。ignoreBOM 则决定是否忽略字节顺序标记，应该根据输入协议明确选择，而不是把 BOM 当作普通业务字符处理。

选择错误模式并收尾

读取流程至少要区分三种结果：正常读完、编码错误、上游流被取消。把消费逻辑放进 try...catch，可以让 fatal 解码错误和上游异常进入同一处处理；如果业务还需要停止读取，应由上游控制器或流的取消机制负责，不要把“文本片段暂时为空”当成结束信号。

async function consume(response, onChunk) {
  if (!response.body) throw new Error("响应没有可读取的 body");

  try {
    // fatal 模式下的编码错误会在消费阶段进入 catch。
    const stream = response.body.pipeThrough(
      new TextDecoderStream("utf-8", { fatal: true })
    );
    for await (const chunk of stream) {
      // 这里只处理已经完成编码转换的文本片段，不假设它是一整条消息。
      await onChunk(chunk);
    }
  } catch (error) {
    // 记录真实错误并交给上层决定重试、提示或结束当前任务。
    console.error("流式文本读取失败", error);
    throw error;
  }
}

收尾时不要额外调用一次普通 TextDecoder 去“补最后一块”，否则同一条输入可能被重复解码。让管道自然结束，或按流 API 的取消约定关闭上游，消费者只负责处理已经收到的文本。

沉淀可复用的流式文本工作流

实际项目可以按下面的顺序落地：

常见误区有三个：每个分块独立解码、把空片段当作流结束、以及在解码层混入业务协议判断。把这三层分开，TextDecoderStream 就会变成一条清晰的字节到文本转换管道。

相关问题

TextDecoderStream 和 TextDecoder 有什么区别？ TextDecoder 适合一次性或手动分块解码；TextDecoderStream 直接作为流转换器连接到 ReadableStream，能把跨分块状态交给管道维护。

为什么读到的 chunk 不是完整 JSON？ 流分块由底层传输决定，文本片段可能停在 JSON 中间。应先缓存并按协议边界拼接，再调用 JSON.parse。

遇到乱码应该先改哪里？ 先确认输入编码和 fatal/ignoreBOM 配置，再确认是否重复解码；不要先用字符串替换掩盖字节层问题。