一个处理日志的脚本,平时文件只有几 MB,跑一次几秒钟。某天日志涨到 80 MB,脚本启动后不久就被系统杀掉,终端只留下一行:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

代码里没有任何循环,只有一句 fs.readFileSync(logPath, 'utf8'),然后把内容按行切开。问题不在逻辑,在读取方式:它要求 Node 一次性把 80 MB 文本读进内存,再转成字符串,字符串还可能是字节数的两倍。堆一下就顶到上限。

另一个更隐蔽的现象是「内存不炸但一直涨」。用 pipe 把一个读得快、写得慢的组合接起来,源端不停产出,目标端跟不上,中间的数据就堆在内存里。进程不报错,RSS 却缓慢上升,最后被容器杀掉,看起来像「内存泄漏」,其实是没处理背压。

这篇讲 stream:它是什么、为什么能解决大文件、背压的信号怎么读、pipe 和 pipeline 差在哪,以及什么时候其实不该用流。所有数字都来自本机实测,Node 版本 v24.21.0,Windows x64。

流是什么:把一次搬运拆成很多小段

流是一种处理数据的抽象:不把全部数据一次拿到手,而是一段一段地读、一段一段地处理。生活里的类比是用水管接水,而不是拿桶去河里舀一桶。对文件来说,流每次只读一小块(默认 64 KB),处理完再读下一块,所以内存占用和文件大小基本无关。

Node 有四种流:可读流(Readable)负责产出数据,可写流(Writable)负责接收数据,双工流(Duplex)既能读也能写,转换流(Transform)是双工流的一种,读进来的数据经过处理后从写端出去。fs.createReadStream 是可读流,fs.createWriteStream 是可写流,zlib.createGzip() 是转换流,网络 socket 是双工流。

Readable产出数据。文件读流、HTTP 请求体、标准输入都属于这一类。
Writable接收数据。文件写流、HTTP 响应、标准输出都属于这一类。
Duplex读写各一条通道,互不干扰。TCP socket 是典型例子。
Transform读写相连,读进来的数据被加工后写出去。压缩、加密、解析都靠它。

消费一个可读流有三种写法。老式写法是监听 data、end、error 三个事件;新式写法是 for await (const chunk of stream),把流当成异步迭代器;工程里最常用的是 pipeline,把多个流串起来并统一处理错误。三种写法都能用,区别在错误处理和背压是否自动处理。

const fs = require('node:fs');

const rs = fs.createReadStream(file, { highWaterMark: 64 * 1024 });
for await (const chunk of rs) {
  total += chunk.length;
}

for await 的好处是自动处理背压:循环体没执行完,流不会再产出下一块。它也会在流出错时抛出异常,用 try/catch 接住即可。缺点是写法偏「同步」,容易让人以为每次 chunk 是完整的业务单位,实际上它只是文件系统碰巧返回的一块字节,边界和换行、字符都没有关系。

监听 data 事件则会把流切到「流动模式」,数据一有就推给你,只有 pause() 能停。这种模式最省事,也最容易忽略背压:事件处理函数是同步执行的,处理慢了流并不会等你,它只会继续推。写文件时如果在处理函数里做 CPU 密集操作,内部队列就会堆积。for await 和 pipeline 用的是暂停模式,天然不会出现这个问题。

readFile 为什么会把内存顶上去

我用一个 50 MB 的二进制文件做了对比。先记录进程的 rss(常驻内存,单位字节),再 await fs.readFile(file),读完再记录一次。两次差值是 50.3 MB,几乎等于文件大小。这说明 readFile 的语义就是「把整个文件放进内存」,文件多大,内存就涨多少。

size MB 50.0
readFile rss +MB 50.3 bytes 52428800
stream bytes 52428800 rss +MB 17.9

同一个文件换成 createReadStream 逐块读,峰值 RSS 只增加了 17.9 MB。这 17.9 MB 不是文件内容,而是 V8 堆、Buffer 池、文件系统缓冲和 GC 还没回收的临时对象。它和文件大小无关:文件涨到 500 MB,这个数字也不会跟着涨到 500 MB。

但流也不是「零内存」。每块数据仍然要占内存,默认块大小由 highWaterMark 控制。可读流的默认值是 65536 字节,也就是 64 KB;可写流是 16384 字节,16 KB。我打印 createReadStream(file).readableHighWaterMark 和写流的 writableHighWaterMark,结果正是这两个数。调大块大小能减少系统调用次数,但会增加单次内存占用;调小则相反。

字符串还有一层放大。readFile(path, 'utf8') 先拿到 Buffer,再解码成 JavaScript 字符串,V8 内部用 UTF-16 存储,纯 ASCII 之外的内容每个字符占 2 字节。80 MB 的 UTF-8 文本解码后可能占 160 MB 堆,加上 Buffer 本身,峰值接近 240 MB。所以「文件 80 MB,内存 512 MB 应该够」这种估算,经常在真实数据上翻车。

所以「读文件」的选择标准很具体:文件小于几 MB、需要整体解析(比如 JSON.parse)、需要随机访问中间内容,用 readFile 更简单;文件大小不确定、可能到几十上百 MB、只需要顺序处理,用流。不要因为「流更高级」就把所有读取都改成流,小文件用流反而多一层复杂度和事件开销。

背压:write 返回 false 不是失败

背压(backpressure)是「下游处理不过来时,上游要停下来等」的机制。没有它,源端按自己的速度产出,目标端按自己的速度消费,中间的差值只能堆在内存里。堆到一定程度,进程就被杀了。

Node 的可写流用 write() 的返回值表达这件事。返回值不是「写成功或失败」,而是「内部缓冲区是否还装得下」。返回 true 表示可以继续写,返回 false 表示缓冲已超过 highWaterMark,应该停下来等 drain 事件再继续。

const ws = fs.createWriteStream(out);
console.log(ws.writableHighWaterMark);          // 16384
const ok = ws.write(Buffer.alloc(1024 * 1024)); // false
console.log(ok, ws.writableNeedDrain);          // false true
ws.on('drain', () => console.log('drain fired'));
ws.end();

我一次写 1 MB 进去,返回值是 false,writableNeedDrain 是 true,随后 drain 事件触发。注意 1 MB 远大于 16 KB 的阈值,但 write 并没有拒绝写入,它只是告诉你「别再往里塞了」。highWaterMark 是提示阈值,不是硬上限,这一点很多人会误解。

忽略 write 的返回值,是流相关内存问题最常见的原因。循环里不停 write,却不等 drain,数据会在可写流的内部队列里越积越多。代码不报错,内存曲线却一直往上走。

还有一个更基础的坑:可写流必须调用 end() 才会结束,finish 事件也只在 end() 之后触发。我自己写测试时忘了调 end(),脚本直接退出,finish 一次都没打印出来。如果代码在等 finish 做后续动作,就会永远等不到。记住三个事件的顺序:finish 表示「数据都交给底层了」,close 表示「底层句柄关了」,error 表示「中间出了问题」。

手写写入循环时,可以把 write 和 drain 包成一个可等待的动作:返回 false 就 await once(ws, 'drain'),再继续下一块。Node 的 events.once 能把事件转成 Promise,比手写回调清楚。不过既然 pipeline 已经处理了这些,只有在必须精细控制写入节奏时才需要自己写。

pipe 和 pipeline 的区别

readable.pipe(writable) 是最常用的连接方式,它内部会自动处理背压:可写流返回 false 时,可读流会暂停,drain 之后再恢复。所以「用 pipe 就不用管返回值」这句话在大多数场景成立。

但 pipe 有一个致命弱点:它不传播错误。源流出错时,目标流不会自动关闭,也不会收到通知;中间任何一段出错,其他段可能还在运行,句柄和内存都不释放。目标流出错时,源流也可能继续读,白白消耗 I/O。

pipeline 解决的正是这件事。它把多个流串起来,任何一段出错就销毁所有流,并把错误交给回调或 Promise。用 node:stream/promises 的版本可以直接 await,错误用 try/catch。

const { pipeline } = require('node:stream/promises');

await pipeline(
  fs.createReadStream(src),
  fs.createWriteStream(dest)
);
console.log('pipeline done');

我实测复制那个 50 MB 文件,pipeline 正常结束,目标文件大小是 52428800 字节,和源文件一致。换成手写循环加 pipe,也能跑通,但错误路径要自己补:源错误、目标错误、中途销毁、Promise 拒绝,少写一个就会留下悬挂的句柄。

用 pipeline 时注意它会把所有流都结束掉,包括目标流。如果目标流还要继续写别的数据(比如一个复用的日志流),不要直接传进去,要么包一层 PassThrough,要么改用手动 pipe 并自己管理生命周期。

还有一种常见误解:pipe 返回目标是给你继续链式调用的,不是错误句柄。rs.pipe(ws).pipe(zip) 这种链式写法看着顺,但中间任何一段出错,错误都不会传到最后的回调。流链越长,越应该用 pipeline 一次串起来。

按行读:readline 与分片读取

流给你的块是字节,不是行。想按行处理日志,直接对每块 split('\n') 会出问题:一行可能被切成两块,处理逻辑会把半行当成完整行。解决办法是用 readline,它在流之上做行缓冲,负责拼接跨块的内容。

const readline = require('node:readline');
const rl = readline.createInterface({
  input: fs.createReadStream(file),
  crlfDelay: Infinity
});
let n = 0;
rl.on('line', (line) => { n += 1; console.log('line', n, JSON.stringify(line)); });
rl.on('close', () => console.log('close', n));
line 1 "line1"
line 2 "line2"
close 2

crlfDelay: Infinity 让 Windows 的 \r\n 也被当成一个换行,不会在行尾留下 \r。这个选项在处理跨平台文件时几乎是必需的,否则按行取到的字符串末尾会多一个不可见字符,比较和解析都会莫名失败。

readline 也能异步迭代:for await (const line of rl),不用注册 line 事件。它同样处理背压,循环体慢的时候输入流会暂停。处理超大日志时,这种方式比回调更接近同步代码的直觉,也更容易在循环里 await 下游操作。

只读文件的一段,可以在 createReadStream 里传 { start, end },单位是字节,end 包含在内。做分片下载、断点续传、并行处理大文件时用这个,不要先读整个文件再 slice。注意分片边界可能切断多字节字符,文本处理仍然要用 StringDecoder 或按行读来兜底。

对象模式与转换流

流不只能传字节,还能传对象。打开 objectMode: true 之后,chunk 可以是任意 JavaScript 值,highWaterMark 的计数单位也从字节变成「个数」,默认值变成 16。适合把「一批记录」做成流式处理,避免一次性把整个数组装进内存。

const { Readable } = require('node:stream');
for await (const item of Readable.from([1, 2, 3])) {
  console.log('item', item);
}

Readable.from 能把数组、生成器、异步生成器包成可读流。我实测依次输出 item 1、item 2、item 3。用异步生成器时,每次 yield 就是一块数据,天然支持背压:下游不消费,生成器就停在原地。

转换流用于「读进来、加工、写出去」。压缩、解压、加密、解密、编码转换,标准库都提供了现成的 Transform。pipeline 里串上 zlib.createGzip(),就能一边读一边压一边写,内存占用仍然只和块大小有关,而不是和文件大小有关。

自定义转换流要继承 Transform 并实现 _transform(chunk, encoding, callback),处理完必须调 callback(),否则下游会一直等。忘记调回调是自写 Transform 最常见的错误,表现是整个 pipeline 卡住,没有报错也没有输出。只有在做协议解析或格式转换时才需要自己写,标准库已经封装了常见场景。

pipeline 还支持异步生成器作为中间段。写一个 async function* 接收上游块、yield 加工后的结果,就能在流里做逐块处理,不用手写 Transform 类。生成器的每次 yield 自动受背压控制,代码比实现 _transform 直观。

对象模式下不要塞入带循环引用的对象,序列化和调试都会出问题;跨进程传递时还要能结构化克隆,函数和类实例传不过去。对象流适合进程内的记录批处理,不适合当进程间的传输格式。

字节流

默认模式,块是 Buffer 或 Uint8Array。适合文件、网络、压缩这类二进制场景,highWaterMark 按字节算。

对象流

需要显式开启 objectMode,块是任意对象。适合记录批处理,highWaterMark 按个数算,默认 16。

现象对照

现象真实原因第一步查什么
读大文件时进程被 OOM 杀掉readFile 一次性把整个文件装进内存换成 createReadStream,确认没有别的整体读取
内存缓慢上涨但不报错忽略了 write 的返回值,没等 drain检查写入循环,补 drain 等待或用 pipeline
脚本结束了但 finish 没触发忘了调用 end()确认每条可写流都有 end()
源流出错后目标文件残留半截用了 pipe,错误没有传播换成 pipeline,或手动监听所有 error
按行处理时出现半行块边界和行边界无关用 readline,别对每块直接 split
Windows 文件每行末尾多个字符\r\n 没被识别成一个换行设置 crlfDelay: Infinity
中文在块边界变成乱码多字节字符被切成两半用 StringDecoder 或按行读
调大 highWaterMark 后内存更高阈值变大,单块占用随之变大按实际吞吐调整,不要盲目调大
pipe 之后目标流被意外关闭pipeline 会结束所有流复用流时包一层 PassThrough
自定义 Transform 卡住不结束_transform 里忘了调 callback检查每个分支是否都调用了回调
分片读到的文本开头乱码start 落在多字节字符中间让分片从字符边界开始,或用解码器兜底

边界与代价

流把「内存问题」换成了「控制流问题」。一次性读取的代码是线性的,读、处理、写,三步结束;流的代码是事件驱动的,数据什么时候来、来多少、哪一步先结束,都不由你决定。错误可能发生在任意一段、任意时刻,必须为每条流准备错误路径。

背压也有代价。它能让内存稳定,但不能让慢的消费者变快。下游是慢速磁盘或慢速网络时,上游就是会被拖慢,整体吞吐由最慢的一段决定。这时候要做的是分析瓶颈,而不是加大缓冲;加大缓冲只是把等待换成内存占用,问题迟早还会回来。

调试也更难。块边界不确定,同一个 bug 在小文件上不出现,在大文件上才出现;日志里打印 chunk,看到的是一堆 Buffer,不知道对应业务里的哪条记录。排查流问题通常要同时看三样:当前块大小、写入返回值、有没有 drain 或 error 事件。

还有生命周期。流有 destroy、close、finish、end 多个状态,哪个该在什么时候调用,容易混。经验是:可读流用 destroy 主动停,可写流用 end 正常收尾,出错时统一走 pipeline,不要自己手写销毁逻辑。把生命周期交给标准库,比记住每个状态机便宜。

流本身没有内建超时。网络流卡住时,pipeline 会一直等,直到操作系统层面报错。需要超时就配 AbortController,把 signal 传给 pipeline,到点自动销毁所有流并抛出 AbortError。stream.finished(stream) 也能返回 Promise,用来等某条流真正结束,比监听 close 更可靠。

也不是所有场景都该用流。需要随机访问、需要整体排序、需要把全部数据放进一个数据结构里计算,这些本质上要求数据完整,强行用流只会把逻辑拆碎。流适合「逐条处理、不回头」的场景,判断标准是:处理第 N 条时,是否需要知道第 N+1 条的内容。

小结

流是「分段处理」,内存占用和文件大小脱钩;Node 有可读、可写、双工、转换四类流;readFile 会把整个文件装进内存,50 MB 文件实测让 RSS 涨 50.3 MB,换成流只涨 17.9 MB;可写流的 write 返回 false 是背压信号,要等 drain;pipe 自动处理背压但不传播错误,pipeline 两者都管;按行读用 readline,对象处理用 objectMode。

当天可以自己验证的练习:

  1. 造一个 50 MB 的文件,分别用 readFile 和 createReadStream 读,打印两次 process.memoryUsage().rss 的差值。
  2. 向可写流一次 write 1 MB,打印返回值、writableNeedDrain,并监听 drain。
  3. 写一个可写流但故意不调 end(),观察 finish 是否触发、进程是否直接退出。
  4. 用 pipe 连接一个会抛错的源流,看目标文件是否残留;再换 pipeline 对比。
  5. 用 readline 读一个带 \r\n 的文件,对比设置 crlfDelay: Infinity 前后的行内容。

下一篇讲网络通信:http 模块、fetch、socket。流是网络的底座:HTTP 请求体是可读流,响应是可写流,socket 是双工流。理解了背压,再看「上传大文件为什么要把请求体接进文件流」「响应写到一半客户端断开为什么会报 ECONNRESET」,就都是同一套机制。