一个处理日志的脚本,平时文件只有几 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 是双工流。
消费一个可读流有三种写法。老式写法是监听 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。
当天可以自己验证的练习:
- 造一个 50 MB 的文件,分别用
readFile和createReadStream读,打印两次process.memoryUsage().rss的差值。 - 向可写流一次
write1 MB,打印返回值、writableNeedDrain,并监听drain。 - 写一个可写流但故意不调
end(),观察finish是否触发、进程是否直接退出。 - 用
pipe连接一个会抛错的源流,看目标文件是否残留;再换pipeline对比。 - 用
readline读一个带\r\n的文件,对比设置crlfDelay: Infinity前后的行内容。
下一篇讲网络通信:http 模块、fetch、socket。流是网络的底座:HTTP 请求体是可读流,响应是可写流,socket 是双工流。理解了背压,再看「上传大文件为什么要把请求体接进文件流」「响应写到一半客户端断开为什么会报 ECONNRESET」,就都是同一套机制。