Node.js / 系统课时
使用管道传输数据
使用管道传输数据
Node.js 的流可以把“读取、转换、写入”连接成连续的数据链,不必先把整个文件放进内存。本课用一个可运行示例完成文本转大写并写入文件,同时说明 pipe() 适合什么场景、为什么生产代码更常用 pipeline() 统一处理完成与失败。
学习目标
- 能用
pipe()理解 Readable、Transform、Writable 的连接关系。 - 能用 Promise 版
pipeline()完成一条可等待、可捕获错误的数据链。 - 能根据完成通知和错误处理需求选择合适的连接方式。
用 pipe 理解数据怎样穿过三段流
最短的数据链通常是“数据源 → 转换流 → 目标流”。Readable.pipe(destination) 会把上游数据送给下游,并自动协调正常的流量控制;如果中间是 Transform,因为它同时可读、可写,就能继续连接下一段。典型写法是 source.pipe(transform).pipe(destination)。

pipe() 很适合短链路,但“源流结束”不等于“目标已经完成全部写入”。需要等待结果时,应关注 Writable 的 finish;需要把整条链的错误当成一个整体处理时,直接使用 pipeline() 更省事。
用 pipeline 等待整条链完成
下面示例适用于 Node.js 15 及以上版本,使用 node:stream/promises 的 Promise 版 pipeline()。它把内存中的两段文本交给 Transform 转成大写,再写入 output.txt;只有整条链完成后才读取文件验证。
const { Readable, Transform } = require('node:stream');
const { pipeline } = require('node:stream/promises');
const { createWriteStream } = require('node:fs');
const { readFile } = require('node:fs/promises');
async function main() {
const source = Readable.from(['node\n', 'stream\n']);
const upper = new Transform({
transform(chunk, encoding, callback) {
// Transform 必须通过 callback 交出转换后的数据或错误。
callback(null, chunk.toString('utf8').toUpperCase());
},
});
await pipeline(source, upper, createWriteStream('output.txt'));
const result = await readFile('output.txt', 'utf8');
process.stdout.write(result);
}
main().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});预期输出
NODE
STREAM同时,当前目录会生成内容相同的 output.txt。如果目标目录不存在或写入失败,pipeline() 返回的 Promise 会拒绝,错误进入 catch,不会把“只完成了一半的链路”误判为成功。
pipe 和 pipeline 怎样选
| 场景 | 更合适的方式 | 直接判断标准 |
|---|---|---|
| 很短的链路,只关心把数据接过去 | pipe() |
已单独处理各流的 error,也不需要 await 整体完成 |
| 文件处理、压缩、上传等完整任务 | pipeline() |
希望一个错误入口处理整条链,并等待最终完成 |
| 中间有多个 Transform | pipeline() |
链路越长,集中处理完成与失败越容易检查 |
| 只是把一个 Readable 接到一个 Writable | 两者都可 | 若后续代码依赖写入完成,优先 pipeline() |
Node.js 10 及以上已经提供回调版 stream.pipeline();Node.js 15 及以上可以使用本课的 node:stream/promises 写法。维护旧项目时先检查运行时版本,不要把 Promise 版 API 直接复制到较老的 Node.js。
验证管道是否真的完成
验收时不要只看“程序没有报错”。本例至少检查三件事:await pipeline(...) 已正常返回、output.txt 确实存在、文件内容严格等于两行 NODE 和 STREAM。若转换流忘记调用 callback,整条链会一直无法完成;若回调传入错误,pipeline() 应立即进入失败路径。
当任务涉及文件复制、压缩、解压、HTTP 响应落盘等多段流处理时,把每一段都放进同一个 pipeline(),并在它完成之后再执行“移动文件、写数据库状态、返回成功响应”等后续动作,可以避免把尚未写完的数据当成最终结果。