FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

Node.js 啃下多 GB 文件,靠一个常被忽略的布尔值

先手写一次停止信号,再交给 stream.pipeline() 处理背压,文件再大内存也保持平稳。

分享微博

要点速览

  • 读文件通常比写文件快,数据会在缓冲区里堆积。write() 返回 false 时,就停止写入
  • pipeline 会替你处理背压,出错时关闭链上所有流,而一串 .pipe() 调用做不到这一点
  • 用 readline 逐行读取,设置 crlfDelay: Infinity,并且在创建接口和开始循环之间不要 await 任何东西
数据管道示意图,包含四个方块:读取文件(createReadStream)、readline、clean() 和写入文件(createWriteStream),数据从左向右流动。一条橙色箭头从写入文件方块反向指回读取文件方块,标注为:write() 返回 false 时,读取暂停,直到 'drain' 事件触发。highWaterMark 默认值为 64 KiB。
write() 返回 false 时,pipeline 暂停读取端,直到 'drain' 事件触发,因此内存里只存放少量数据块,不会随文件大小膨胀。来源:Node.js 文档中关于流和背压的说明。

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”具体得多。当岗位描述提到把客户数据接入系统时,就是展示这个仓库的时机。

一旦内存不再随文件大小增长,“稍微大一点”的文件只不过是多跑几分钟。这时值得问客户的问题是:他们的数据坏在哪里。

这篇文章对你有帮助吗?

7 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力按结果收费时,计数器就是发票账单在周期末才对账,配额却要逐个事件检查,所以两者必须拆成两套系统、各按各的节奏运行。