Node.js 26.5.0 的 Blob.textStream() 怎么用：流式读取文本的边界与核对

Node.js 26.5.0 在 Blob 上补了一个很实用的入口：blob.textStream()。它返回 Web Streams API 的 ReadableStream，适合把一段已经放进 Blob 的文本逐块交给后续处理；如果只是想一次拿到完整字符串，原来的 text() 仍然更简单。真正需要注意的是版本门槛、分块不等于按行，以及流被消费后不能再重复读取。

结论先放在这里：Node.js 26.5.0 及以上可以用 textStream() 读取 Blob 文本流；它解决的是“按块读取并接入 Web Streams”问题，不会自动把数据切成完整行，也不会让大文件在创建 Blob 时完全绕开内存占用。

Node.js 26.5.0 新增了什么

这次变化不是把 Blob 变成文件流，而是增加了一个文本专用的读取入口。Node.js 官方 26.5.0 发布说明把 blob.textStream() 列为 Buffer 模块的新增能力；当前 API 文档也标明它从 v26.5.0 开始提供，并返回 ReadableStream。

可以先用一个最小例子确认运行时：

import { Blob } from 'node:buffer';

const blob = new Blob(['order=1001\nstatus=paid\n']);

if (typeof blob.textStream !== 'function') {
  throw new Error('需要 Node.js 26.5.0 或更高版本');
}

for await (const chunk of blob.textStream()) {
  console.log('收到文本块：', chunk);
}

这里的 chunk 是字符串，但不要把它误认为一行。数据量变大、链路接入转换流后，块的边界仍然由流实现决定。

text()、stream() 和 textStream() 怎么选

如果后面紧接着是 JSON 解析，通常仍然使用 text() 更自然，因为标准 JSON 解析需要完整字符串。textStream() 更适合日志筛选、文本计数、增量转换或把数据交给另一个 Web Stream。

按块读取时，怎样正确处理跨块换行

下面用一个小型日志过滤器说明问题。每次收到文本块后，先和上一次留下的残片拼接，再按换行拆分；最后一段不完整的内容要留到下一块，循环结束后再补一次处理。

import { Blob } from 'node:buffer';

const source = new Blob([
  'id=1001 level=info\n',
  'id=1002 level=warn message=timeout\n',
  'id=1003 level=info\n'
]);

let rest = '';
for await (const chunk of source.textStream()) {
  const lines = (rest + chunk).split('\n');
  rest = lines.pop() ?? '';

  for (const line of lines) {
    if (line.includes('level=warn')) {
      console.log('告警：', line);
    }
  }
}

if (rest) {
  console.log('末尾残片：', rest);
}

生产代码里不要依赖“每个块刚好是一行”这种偶然现象。尤其是把 textStream() 接到网络响应、转换流或文件处理链时，换行符可能被拆开，甚至一个中文字符也可能跨底层字节块；文本流入口会负责解码，但不会替你完成业务分帧。

把 textStream() 接入 Web Streams 转换链

当处理逻辑可以逐块完成时，可以用 TransformStream 把文本统一转成大写、统计字符数或剔除空行。下面的转换不保存全部正文，只输出处理后的结果。

import { Blob } from 'node:buffer';

const normalize = new TransformStream({
  transform(chunk, controller) {
    const cleaned = chunk.replaceAll('\\r\\n', '\\n').trim();
    if (cleaned) controller.enqueue(cleaned + '\\n');
  }
});

const input = new Blob([' A\\r\\n', '\\nB\\r\\n']);
const readable = input.textStream().pipeThrough(normalize);

for await (const chunk of readable) {
  process.stdout.write(chunk);
}

这个例子只展示流的连接方式。若业务要求按行输出，还是要把“残片缓存”放进转换流内部，而不是把每个 chunk 直接当成记录。

升级前后的核对清单

• 运行 node --version，确认实际进程使用的是 26.5.0 或更高版本，不要只看开发机上的版本。
• 在 CI 和容器启动阶段做一次 typeof blob.textStream 能力检测，旧版本给出明确提示。
• 如果输入本来来自超大文件，先确认 Blob 的创建方式；把文件完整读进 Blob 后再调用文本流，并不会消除前面的内存成本。
• 给转换链补上流关闭、异常和取消测试，特别是中途停止读取时的资源回收。

常见问题

Node.js 24 能直接调用 textStream() 吗？

不能把它当作 Node.js 24 的稳定能力。官方文档标记该方法从 v26.5.0 开始提供，跨版本项目应先做能力检测，或继续使用 text() 与 stream()。

textStream() 会按换行符返回字符串吗？

不会。它返回文本块，块与行是两种边界；按行处理要自己缓存末尾残片，并在流结束时处理最后一段。

textStream() 比 text() 更省内存吗？

读取阶段可以避免把完整文本再拼成一个结果字符串，但 Blob 本身如何创建仍然决定了前置内存成本。对真正的大文件，应优先考虑文件流或网络流的端到端处理。

同一个 Blob 可以先 text() 再 textStream() 吗？

Blob 本身可以生成不同的读取对象，但业务上不要把一次消费结果和另一次消费路径混在一起；需要两条独立处理链时，明确创建并管理各自的读取流程。

小结

Blob.textStream() 是 Node.js 26.5.0 对 Web Streams 方向的一次小而明确的补充：它让 Blob 文本可以直接以字符串块进入流式处理链。选型时先看是否需要完整字符串，再看是否能接受自行处理分帧；升级时把版本检测、跨块换行和 Blob 创建成本一起核对，才不会把“有了文本流”误解成“所有大文件处理都自动变省内存”。