前端 fetch 大文件时怎么用 ReadableStream 逐块处理

读取大文件时，先别把响应直接交给 response.text() 或 response.blob()。这两个调用会等整个响应准备好再交给业务层；更稳妥的做法是读取 response.body，让 ReadableStream 一块一块地交付数据，再在消费循环里解码和处理。

最小方案是：检查 response.ok，把 response.body 通过 TextDecoderStream 转成文本流，用 for await...of 消费；每一块处理完后再请求下一块，用户取消时调用 AbortController.abort()。

ReadableStream 的最小消费链路：从响应块到文本

前端要处理下载日志、导出结果或服务端持续输出时，可以把响应体当成一条数据管道。Response.body 暴露的是 ReadableStream，读取器会返回 done 和 value：done 表示流是否结束，value 才是当前块。它的边界由网络和浏览器决定，不应把“一块”理解成一行或一个完整 JSON。

async function consumeText(url, onChunk) {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  if (!response.body) {
    throw new Error("当前环境没有可读响应流");
  }

  // 解码器会保留跨块的 UTF-8 半字符，避免中文被拆坏。
  const textStream = response.body.pipeThrough(new TextDecoderStream());
  for await (const chunk of textStream) {
    await onChunk(chunk);
  }
}

这里的 onChunk 可以把文本追加到界面、送入增量解析器，或写进应用自己的缓冲区。不要假定每个 chunk 都是完整 JSON；如果协议按换行分隔，就在业务缓冲区里拼接到换行符再解析。

为什么 TextDecoderStream 比逐块 toString 更稳

网络块是字节边界，中文字符却可能由多个 UTF-8 字节组成。若拿到一块就单独解码，字符恰好被拆在两块之间时，容易出现替换字符。TextDecoderStream 把解码器放进流管道，由它维护跨块状态；这比在每次 read() 后临时创建解码器更适合持续文本。

如果必须使用底层读取器，可以让同一个解码器持续工作：

async function readWithReader(response, onText) {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        // flush=true 处理最后可能残留的多字节字符。
        const tail = decoder.decode();
        if (tail) await onText(tail);
        break;
      }
      await onText(decoder.decode(value, { stream: true }));
    }
  } finally {
    reader.releaseLock();
  }
}

两种写法不要混用同一个响应体的读取权：调用 getReader() 会锁定流，另一个消费者要等锁释放后才有机会读取。

背压、取消和异常要在同一个消费循环里处理

逐块处理并不意味着浏览器会无限快地把数据塞进内存。上例中 await onChunk(chunk) 没有完成前，循环不会主动读取下一块，这就是应用层最容易理解的背压边界。处理队列仍然很大时，应暂停或限流业务消费，而不是继续把块复制到多个数组里。

async function streamFile(url, onChunk, signal) {
  const response = await fetch(url, { signal });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  if (!response.body) throw new Error("ReadableStream 不可用");

  try {
    for await (const chunk of response.body.pipeThrough(new TextDecoderStream())) {
      if (signal.aborted) return;
      // 处理完成后循环才会继续，避免无界积压。
      await onChunk(chunk);
    }
  } catch (error) {
    if (signal.aborted) return;
    throw error;
  }
}

const controller = new AbortController();
cancelButton.addEventListener("click", () => controller.abort());
streamFile("/exports/large.ndjson", appendText, controller.signal);

这里要区分三类问题：非 2xx 是服务端或权限问题；循环中的异常是读取、解码或业务处理失败；abort() 则是用户主动结束。把取消当成普通错误上报，会让监控产生大量无意义告警。

落地前检查响应头和浏览器边界

如果项目仍需支持没有异步迭代响应流的旧环境，可以回退到 getReader() 循环；不要为了“兼容”把大文件重新复制成多个完整字符串。对二进制下载则直接处理 Uint8Array，或交给合适的写入流。

常见问题

ReadableStream 的一个 chunk 是一行吗？

不是。它只是当前可读的数据块，可能截断一行、一个 JSON 或一个 UTF-8 字符。协议分隔需要由业务缓冲区处理。

为什么已经用了流，内存仍然持续上涨？

常见原因是把每个块都保存进数组、重复拼接完整字符串，或消费速度低于生产速度。先检查是否存在无界缓存，再让处理完成成为下一次读取的前置条件。

调用 abort 后为什么还会执行一次回调？

取消发生在异步边界附近时，已经取到的当前块可能仍在处理。回调开头检查 signal.aborted，并在 catch 中把主动取消与真正异常分开即可。

把大响应改为流式消费，关键不在于换一套 API，而是明确三条边界：字节如何变成文本、处理完成后何时继续读取、用户取消后哪些工作必须停止。先用 TextDecoderStream 和有限的消费队列跑通，再根据协议决定是否需要底层 reader。