Node.js Stream:读写、复制、压缩与双向通信
🎯 引言
学完这篇文章,你能按块读写文件、用 pipeline 复制和压缩文件,并用双工流收发数据。
🧱 流让数据一部分一部分地处理
Stream,中文叫流,是逐步接收或输出数据的方式。文件较大或内容持续产生时,程序可以取得一部分就处理一部分,不必等全部内容放进内存。
readFile 即使采用异步方式,也会在读完整个文件后把完整内容交给你。流则持续交付数据块,也就是本次到达的一段数据;一块不一定对应一行文字或一条完整消息。
读取一个小配置时,readFile 通常更直接;复制较大文件、处理持续网络内容时,流更适合控制数据积压。流自己仍需要暂存数据的缓冲区,不是完全不占内存。
📖 Readable:数据从这里读出来
Readable 是可读流,负责向程序提供数据。读取文件可以用 createReadStream 创建一个数据源。
本篇使用 Node.js 24.19.0。先准备 UTF-8 编码的 note.txt,内容为 hello。保存 read-stream.mjs,先写:
import { createReadStream } from 'node:fs'
const source = createReadStream('note.txt', { encoding: 'utf8' })
source 是可读流对象,不是文件内容。encoding: 'utf8' 让它以字符串交付文本;不指定编码时,文件流通常交付 Buffer 字节对象。
接着追加消费代码:
try {
for await (const chunk of source) {
console.log(chunk)
}
} catch (error) {
console.error('读取失败:', error.code)
}
运行 node read-stream.mjs,小文件通常只输出一块 hello。for await 逐次取得异步到达的数据,读完后循环结束;文件不存在时会进入 catch,报告 ENOENT。
指定文本编码后,流会处理跨块字符边界,避免把一个汉字的部分字节单独解码。但它不会帮你按行切分,因此不要认为每次 chunk 都是完整一行。
✍️ Writable:数据往这里写进去
Writable 是可写流,负责接收数据。可以把它作为文件输出目标。下面独立保存为 write-stream.mjs:
import { createWriteStream } from 'node:fs'
const target = createWriteStream('stream-note.txt', { flags: 'wx' })
target.on('error', error => console.error(error.code))
target.on('finish', () => console.log('写入完成'))
target 是可写对象,flags: 'wx' 要求新建文件;目标已经存在时会报告 EEXIST,避免覆盖。两个监听分别接收失败和完成通知,创建对象不代表文件已经写好。
继续追加:
target.end('hello')
end 可以提交末尾内容,并声明“后面不再写入”。成功时文件包含 hello,finish 监听输出 写入完成;end 返回流对象,不是保存后的文件内容。
🧰 pipeline:连接、等待并统一接收失败
复制文件就是把可读流的数据持续送入可写流。 准备内容为 hello 的 source.txt,新建 copy.mjs,先创建两端:
import { createReadStream, createWriteStream } from 'node:fs'
import { pipeline } from 'node:stream/promises'
const source = createReadStream('source.txt')
const target = createWriteStream('target.txt', { flags: 'wx' })
这里导入的是 Promise 版本,可以用 await 等待整体结果。随后立即连接并等待:
try {
await pipeline(source, target)
console.log('复制完成')
} catch (error) {
console.error('复制失败:', error.code)
process.exitCode = 1
}
运行 node copy.mjs,成功时输出 复制完成,target.txt 内容为 hello。成功 Promise 的值为 undefined,我们等待的是完成状态,不是获得复制后的全部内容。
源文件不存在时,Promise 拒绝并报告 ENOENT;目标已存在时,因为 wx 而报告 EEXIST。pipeline 会根据状态销毁相关流,调用者在同一个 catch 中决定怎样反馈失败。
已有代码中也可能用 source.pipe(target) 连接两端。pipe 返回目标流对象,不能用 await 等待复制结束,也不负责统一处理整条链路的错误;本篇复制和压缩任务使用 Promise 版本的 pipeline。
🔄 Duplex:用同一个连接发送和接收数据
Duplex 用于需要双向传输的场景,例如客户端向服务端发送数据,同时接收服务端的数据。 Node.js 的网络连接对象 socket 就是现成的 Duplex,日常使用它即可,不必自己实现一个 Duplex 类。
下面让客户端发送 hello,服务端发送 欢迎连接。两边发送的内容不同,可以看到读取和写入各自负责什么。使用内置 node:net 建立本机 TCP 连接;TCP 在这里提供双方持续收发字节的通道。
准备接收连接的服务端
保存为 server.mjs:
import net from 'node:net'
const server = net.createServer(socket => {
socket.setEncoding('utf8')
socket.on('data', text => console.log('服务端收到:', text))
socket.on('error', error => console.error(error.message))
socket.end('欢迎连接')
})
server.on('error', error => console.error(error.message))
server.listen(3000, '127.0.0.1', () => console.log('等待连接'))
运行 node server.mjs,输出 等待连接。127.0.0.1 表示本机,3000 是这次监听的端口;每次有人连接,回调就取得对应的 socket。
这里 socket 的读侧通过 data 事件接收客户端数据,setEncoding 让收到的字节按 UTF-8 转为文字。写侧通过 end 发送 欢迎连接 并结束本端发送;它仍可以接收对方传来的内容。
客户端用同一个 socket 收发
另存为 client.mjs:
import net from 'node:net'
const socket = net.createConnection({ host: '127.0.0.1', port: 3000 })
socket.setEncoding('utf8')
socket.on('data', text => console.log('客户端收到:', text))
socket.on('error', error => console.error(error.message))
socket.on('connect', () => socket.end('hello'))
保持服务端运行,在另一个终端执行 node client.mjs。connect 事件表示连接已经建立,随后 end 发送 hello 并结束客户端发送。
| 观察位置 | 收到的内容 |
|---|---|
| 服务端终端 | 服务端收到: hello |
| 客户端终端 | 客户端收到: 欢迎连接 |
客户端写出去的是 hello,读到的却是服务端发送的欢迎文字。 这就是 Duplex 两侧独立的含义:它不是把自己写入的数据再读回来。
例子只发送一小段文字;TCP 传输的是字节流,一次 data 事件不保证对应一次发送,较长内容可能分多次到达。双方结束收发后客户端退出,服务端仍等待新连接,练习结束按 Ctrl+C 停止服务端。
需要持续发送时用 write,发送完毕才用 end;本例每端只发送一次,因此直接使用带内容的 end。
🧩 Transform:边读取边压缩文件
Transform 是把输入数据处理后再输出的流,例如将文件内容压缩后保存。 它属于 Duplex,但与网络连接两侧独立收发不同,这里的输出来自对输入的转换。独立创建 compress.mjs,先准备文件读取源:
import { createReadStream, createWriteStream } from 'node:fs'
import { pipeline } from 'node:stream/promises'
import { createGzip } from 'node:zlib'
const source = createReadStream('source.txt')
node:zlib 是内置压缩模块。createGzip 创建 gzip 格式的转换流,接收原始字节并输出压缩字节:
const gzip = createGzip()
gzip 是转换流对象,创建它还没有得到压缩文件。再指定接收压缩字节的目标:
const target = createWriteStream('source.txt.gz', { flags: 'wx' })
最后连接三步:
try {
await pipeline(source, gzip, target)
console.log('压缩完成')
} catch (error) {
console.error('压缩失败:', error.code)
process.exitCode = 1
}
成功后生成 source.txt.gz,用支持 gzip 的工具解压后内容为 hello。顺序表示“读原文、压缩、保存”,不应先把压缩字节按 utf8 转成文字。
⚖️ 背压:写入慢时,让读取暂缓
背压是下游处理不过来时,让上游暂缓继续提供数据的机制。 复制大文件时,如果读取速度高于写入速度,尚未写出的数据就会积压;pipe 和 pipeline 会协调两端速度,避免读取端无限供给。
上面的 copy.mjs 已经使用 pipeline,把源文件换成较大的文件即可沿用,无需为了“大文件”另写一套复制逻辑。它逐块传输,而 readFile 后再 writeFile 需要先在内存中保存完整文件内容。
但如果你自己把读到的每一块都存进数组,仍然会积累整个文件;同时启动很多复制任务也会增加总内存。使用 pipeline 时保持逐块传递即可,不要再额外收集全部内容。
🪤 每次传输重新创建流
已经结束或失败的流有自己的状态,重试时不要复用原对象,应重新创建两端或整条链路,并明确目标文件如何处理。
在本篇示例中,修改源文件或修复读取错误后,重新执行 node copy.mjs 会重新创建流。如果失败留下了 target.txt,先确认它是本次练习生成的文件并手动删除,再重新执行;否则 wx 会因目标已存在而拒绝写入。
❓ 知识问答
Q1:小文件只有一次输出,是不是没用到流?
不是,内容少时一次就能交付,不能用输出次数判断是否使用流。
Q2:创建可写流就代表完成保存吗?
不代表,需要提交数据并等待完成或失败通知。
Q3:为什么再次复制或压缩会报 EEXIST?
示例使用 wx 拒绝覆盖已有文件。确认目标是自己的练习结果后,手动删除或换一个目标文件名再运行。
Q4:用了 pipeline 就不用 catch 吗?
仍然需要。pipeline 将链路失败交给调用者,catch 负责报告失败并设置退出码。
🧪 小练习
先完成文件复制与压缩,检查复制内容和解压后的内容是否与源文件一致。再把读取目标改为不存在的文件,观察错误码与退出结果。
// 请在这里编写代码
🎉 现在可以用自己的例子验证这些用法啦!
