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

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

原文: https://fdetimes.net/zh/guides/node-js-streams-backpressure-large-files/

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 内置的逐行读取工具。

```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'` 事件。

```js
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` 会自行管理整条链上的错误。完整的清洗工具，精简版如下：

```js
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` 函数几千万次，并埋入一些坏行。然后写出很多人第一次会写的版本：

```js
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 版本，在运行期间每秒打印一次内存：

```js
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` 的中间环节，出错时链上的每个流都会被清理。

```js
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` 循环打印前五行，马上就能回答这个问题：

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

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

**本周动手试试:**

- 造一个几 GB 的假 NDJSON 文件，先后运行 readFile 版本和 pipeline 版本，记录两者 process.memoryUsage() 给出的 RSS
- 写一个小型 head 工具，用 for await 加 break 打印任意 CSV/NDJSON 文件的前 N 行，记得关闭读取流
- 在 GitHub README 中加入两个版本的内存表格，再写一段说明 pipeline 如何按行号报告错误，让看到仓库的人知道你考虑过如何向客户反馈

## 信源

- [Backpressuring in Streams | Node.js Learn](https://nodejs.org/learn/modules/backpressuring-in-streams)

- [Stream | Node.js documentation](https://nodejs.org/api/stream.html)

- [A guide to reading and writing Node.js streams](https://blog.platformatic.dev/a-guide-to-reading-and-writing-nodejs-streams)

- [Readline | Node.js documentation](https://nodejs.org/api/readline.html)

- [GitHub - ndjson/ndjson-spec: Specification](https://github.com/ndjson/ndjson-spec)

- [JSON Lines](https://jsonlines.org/)

- [CSV Parse - Async iterator API](https://csv.js.org/parse/api/async_iterator/)
