Node.js 啃下多 GB 文件,靠一个常被忽略的布尔值
先手写一次停止信号,再交给 stream.pipeline() 处理背压,文件再大内存也保持平稳。
要点速览
- 读文件通常比写文件快,数据会在缓冲区里堆积。write() 返回 false 时,就停止写入
- pipeline 会替你处理背压,出错时关闭链上所有流,而一串 .pipe() 调用做不到这一点
- 用 readline 逐行读取,设置 crlfDelay: Infinity,并且在创建接口和开始循环之间不要 await 任何东西
Node.js 中 Writable 流的 write() 方法会返回一个布尔值,这个值很容易被忽略。文件只有几十 MB 时,忽略它也无妨。但当客户发来一份几个 GB 的订单导出文件时,这个值决定了进程能顺利处理完,还是在中途因内存不足而崩溃。
Node.js 文档把这个问题叫作背压(backpressure):接收端比数据源慢时,数据会像堵车一样堆积。写磁盘通常比读磁盘慢得多,所以压缩或清洗一个文件再写回去,正是典型场景。如果读取端不知道何时该停,两者的速度差就会留在 RAM 里。
对前线部署工程师(FDE)来说,这不是纸上谈兵。设想到客户现场的第一天:对方交给你一份导出文件,可能是 ERP 导出的 CSV,也可能是日志系统导出的 NDJSON。本指南一步步搭建一个清洗这类文件的工具,在自己的笔记本上就能马上运行。
要做什么,需要准备什么
假设客户发来 orders.ndjson,每行一条订单。有些行是损坏的 JSON,有些是空行,而且文件是在 Windows 机器上导出的。目标是写出 orders.clean.ndjson,同时整理出一份坏行行号清单,发回给客户。
你需要较新版本的 Node.js、一个代码编辑器,以及最后 CSV 部分要用的 csv-parse 库。代码使用 ES 模块,为了便于阅读做了精简。用于生产环境之前,请对照官方文档核对各项选项。
第 1 步:逐行读取,而不是一次读完
NDJSON 规范规定,每一行都是一个独立的 JSON 文本,不得包含换行符。因此最自然的处理单位就是行,这也符合 JSON Lines 的思路:结构化数据,一次处理一条记录。readline 正是 Node.js 内置的逐行读取工具。
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
const rl = createInterface({
input: createReadStream('orders.ndjson'),
crlfDelay: Infinity,
});
let n = 0;
for await (const line of rl) {
n++;
}
console.log('行数:', n);
文件中含有 \r\n 时(Windows 导出的文件就是这样),readline 文档建议使用 crlfDelay: Infinity 选项。验证方法:用另一个你信得过的工具统计行数,与 n 对比。
readline 文档明确提醒了一个陷阱:如果在创建接口和开始 for await 之间插入任何异步操作,就可能丢行。不要在中间塞一句 await db.connect()。先连接,再创建接口。
第 2 步:亲眼看看停止信号
在动用自动化工具之前,先手写一次,理解其中的机制。缓冲区超过 highWaterMark 时,write() 返回 false。根据 Node.js 文档,这时背压机制开始生效:读取端暂停,直到写入端重新就绪,信号是 'drain' 事件。
import { createWriteStream } from 'node:fs';
const out = createWriteStream('orders.clean.ndjson');
async function writeLine(text) {
if (!out.write(text)) {
await new Promise((resolve) => out.once('drain', resolve));
}
}
第 1 步的 for await 循环会等每次迭代结束,所以在循环里 await writeLine(...) 时,读取端会自动暂停,等待写入端。去掉 await,程序照样能跑,但文件一大,尚未写出的数据就会在内存里堆积。
由于读取端愿意等待,RAM 只需存放等待写入的数据,而不是整个文件。无论文件是 1 GB 还是 10 GB,这部分等待数据都一样小。
第 3 步:让 pipeline 扛下难的部分
手写 drain 处理有助于理解机制,但实际代码中请使用 pipeline。Node.js 指南说明,用 pipe 或 pipeline 连接流时,背压会被自动处理;它给出的 pipeline 示例里没有一行 drain 代码。出问题时,pipeline 还会把错误传回给你,并关闭链上所有流。
这正是它与 .pipe() 的最大区别:根据 Node.js 文档,如果 Readable 中途抛出错误,目标 Writable 不会自动关闭,你得自己清理,避免内存泄漏。Platformatic 的工程博客也强调,pipeline 会自行管理整条链上的错误。完整的清洗工具,精简版如下:
import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createInterface } from 'node:readline';
const badLines = [];
async function* lines() {
const rl = createInterface({
input: createReadStream('orders.ndjson'),
crlfDelay: Infinity,
});
for await (const line of rl) yield line; // 中间不要有 await
}
async function* clean(source) {
let n = 0;
for await (const line of source) {
n++;
if (line.trim() === '') continue; // 我们的选择:跳过空行
try {
yield JSON.stringify(JSON.parse(line)) + '\n';
} catch {
badLines.push(n);
}
}
}
await pipeline(lines, clean, createWriteStream('orders.clean.ndjson'));
console.log('坏行:', badLines.length, badLines.slice(0, 20));
验证这一步:造一个故意含几行损坏数据的文件,重新运行,看 badLines 是否恰好包含这些行号。
注意,如果文件大面积损坏,badLines 会不断增长。生产版本应该通过 pipeline 本身把坏行写入单独的文件,而不是存在数组里。
第 4 步:别轻信承诺,动手测量
“内存不随文件增长”这句话,只有亲眼看到才可信。首先生成一个几 GB 的假 NDJSON 文件,例如循环调用第 2 步的 writeLine 函数几千万次,并埋入一些坏行。然后写出很多人第一次会写的版本:
import { readFile } from 'node:fs/promises';
const text = await readFile('orders.ndjson', 'utf8'); // 把整个文件载入 RAM
let bad = 0;
for (const line of text.split('\n')) {
try { if (line.trim()) JSON.parse(line); } catch { bad++; }
}
console.log('坏行:', bad);
console.log('RSS(MB):', Math.round(process.memoryUsage().rss / 1e6));
对于第 3 步的 pipeline 版本,在运行期间每秒打印一次内存:
const timer = setInterval(() => {
console.log('RSS(MB):', Math.round(process.memoryUsage().rss / 1e6));
}, 1000);
await pipeline(lines, clean, createWriteStream('orders.clean.ndjson'));
clearInterval(timer);
先用约 100 MB 的文件运行两个版本,再换成几 GB 的文件,记下数字。readFile 版本必须同时在 RAM 中保存文件内容和行数组,内存占用必然随文件大小上升,文件足够大时可能根本跑不完。
pipeline 版本只保存等待写入的数据。你希望看到的是:即使文件大了许多倍,RSS 仍在某个水平附近波动。如果数字持续上涨,就去找代码里还在哪里持有数据,头号嫌疑是 badLines 数组。
第 5 步:CSV 走同一条管道
根据 csv-parse 文档,这个解析器基于 Node.js 原生的 Readable Stream API 构建。因此它可以直接接入 pipeline 的中间环节,出错时链上的每个流都会被清理。
import { parse } from 'csv-parse';
await pipeline(
createReadStream('customers.csv'),
parse(), // 每条记录是一个数组;表头选项见 csv-parse 文档
async function* (rows) {
for await (const row of rows) yield JSON.stringify(row) + '\n';
},
createWriteStream('customers.ndjson'),
);
不要通过 readline 用 split(',') 切分 CSV。只要有一个字段在引号内含有逗号或换行符,后面所有列就会错位,而这类 bug 可能到第几百万行才暴露出来。
第 6 步:预览工具与 break 陷阱
刚拿到一个陌生文件时,先查看它有哪些列,再做别的事。Node.js 的每个 Readable 流都是异步可迭代对象,所以用 for await 循环打印前五行,马上就能回答这个问题:
const file = createReadStream('customers.csv');
let i = 0;
for await (const row of file.pipe(parse())) {
console.log(row);
if (++i === 5) break;
}
file.destroy(); // 保险起见,自己关闭读取流
用 break、return 或 throw 离开 for await 循环时,Node.js 默认会销毁正在迭代的流,这里就是 parse() 创建的流。如果想让这个流继续存活,改为迭代 readable.iterator({ destroyOnReturn: false })。
然而,文件的读取流并不是被迭代的对象。要确保一个 4 GB 的文件不再继续读取,就像最后一行那样,自己用 file.destroy() 关闭它。这个小例子为了简洁用了 .pipe();实际任务仍应通过 pipeline,确保出错时每个流都能关闭。
在客户那里,人们记住的是坏行数
设想这样一幕:收到文件仅仅几分钟后,你回复“有 312 行损坏,行号如下”,而且是在自己的笔记本上跑出来的,没有额外申请服务器。
312 这个数字只是举例。但一份带行号的错误报告能准确告诉客户的数据团队该改哪里,可以大大减少来回沟通。
这个场景值得带进求职申请。一个小型代码仓库复现这一幕:一个埋了坏行的多 GB 假文件、readFile 版本与 pipeline 版本并排运行,再加上第 4 步测得的内存表格,它就能替你讲述“客户现场第一天”的故事。
简历上写这个故事的结果:“以稳定的内存处理多 GB 导出文件,并逐行报告错误”,比“精通 Node.js”具体得多。当岗位描述提到把客户数据接入系统时,就是展示这个仓库的时机。
一旦内存不再随文件大小增长,“稍微大一点”的文件只不过是多跑几分钟。这时值得问客户的问题是:他们的数据坏在哪里。
这篇文章对你有帮助吗?
感谢你的反馈!