JSON 工具箱

Node.js 读大 JSON:stream-json 流式解析与背压实战

结论:186MB 的 JSON 数组用 readFileSync 加 JSON.parse 读,峰值内存 612MB;换成 stream-json 的 streamArray 逐条消费,内存恒定在 104MB。本文给出四种读法的实测对照,讲清 for await 为什么天然背压、data 事件怎么把背压弄丢、写入侧该怎么配 highWaterMark 与 drain。

实战约 5 分钟发布于 2026-11-17更新于 2026-11-17
Node.js 流式解析大 JSON 文件:streamArray 管道与背压实测对照

导入一个 186MB 的 JSON 文件,进程内存冲到 600MB 不是文件大,是 JSON.parse 把整段文本一次性换成了整张对象图——换掉读法,内存曲线就是平的。

一、现象:186MB 的文件,峰值内存 612MB

服务端导入任务是这个问题的高发区:定时同步订单、清洗导出日志、入库历史数据。一段典型写法长这样:

const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);

我们按这条写法在 Node 22.13 上做了基线实测:样本是 480,000 条订单记录的对象数组、文件 186MB(字段含字符串、嵌套对象、数组,模拟真实业务结构),用 /usr/bin/time -v 量最大常驻内存。结果是 1.3 秒读完,但 Maximum resident set size 612MB——文件 186MB,内存 3.3 倍。V8 老生代默认上限 1.4–2GB,几个这样的任务并发,容器就等着被 OOM Kill。

数据不是编的:文本进内存一份(约 186MB),parse 出的对象图再进一份(每条记录的字符串键、嵌套对象头、数组都有额外开销),加上解析过程本身的临时分配,峰值叠到 600MB 很正常。

二、原因:JSON.parse 是整段文本换整张对象图

JSON.parse 的契约是「给我完整文本,还你完整对象图」。它在解析开始前就要求文本全部就位,在解析结束后才把结果一次性交出来。中间没有任何「我先给你前 1000 条」的机会。

对象图的开销可以逐项拆开算,JSON 的内存账 一文已经做过系统测量:字符串每条都要实占空间,对象每个键占一格,数组按元素种类决定每格宽度。结论是十几 MB 的 JSON 解析后翻三五倍是常态,峰值还要再叠一层。

但大部分导入任务根本不需要整张图:逐条写库、逐条过滤、逐条转换,每条记录处理完就可以被垃圾回收。需要的只是「解析到一条就交出一条」的能力——这正是流式解析的定义。

三、改法:streamArray 逐条消费,for await 自带背压

stream-json 把解析器做成 Transform 流,token 级解析,不必等整个文件。顶层是数组时,streamArray() 会在每个元素解析完成的瞬间抛出 {key, value}:

const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');

async function importOrders(filePath) {
  const pipeline = chain([
    fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
    parser(),
    streamArray(),
  ]);
  for await (const { key, value } of pipeline) {
    await saveToDb(value);
  }
}

同样的 186MB 文件、同样的 48 万条记录,这套写法的峰值 RSS 是 104MB,全程恒定。内存里同时只存在「当前元素 + 解析器状态」,前面的元素写完即回收。

这里有个容易忽略的细节:for await 在等待 saveToDb 完成之前不会向解析器要下一条数据,解析器随之中断读文件。数据库越慢,读得越慢——这就是背压,天然形成,不需要你写任何额外代码。dev.to 上一篇 4GB 市政交通日志的摄取复盘用的就是同一条链路,加了 pick({filter:'data'}) 做字段过滤,内存曲线同样平坦。

四、写入侧失守:不暂停的 data 事件会把内存抬回去

流式解析只是管住了读侧。如果写侧不接住背压,内存照样涨回去。最典型的失效写法是 data 事件里做异步写、却不管可写流的缓冲:

// 错误:data 事件 + 异步写,背压完全失效
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // 流不会等你,缓冲区一路膨胀
});

data 事件模式下流照常流动,slowWrite 再慢也不会让上游暂停,积压全部堆在可写流内部缓冲里。我们用同一个 186MB 样本做了对照:写侧接一个「每第 100 块延迟 1ms」的慢速 Writable,不管背压的写法峰值 RSS 冲到 407MB,而 write() 返回 false 时用 await once(sink, 'drain') 暂停的写法是 161MB——差出的 246MB 就是攒在写缓冲里的数据。

// 正确:write() 返回 false 时暂停,drain 后继续
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

两条补充经验:手动拼接流链路时给每条流显式设置 highWaterMark,objectMode 下默认值 16 对大对象偏大;优先用 pipeline()(stream/promises)代替 pipe(),错误传播和清理由它兜底。

五、实测对照:四种写法的峰值内存

写法 样本 峰值 RSS 耗时 适用
readFileSync + JSON.parse 186MB / 48 万条 612MB 1.3s 文件小、要随机访问
streamArray + for await + 慢写库(每条 0.5ms) 同上 104MB(恒定) 由写库节奏支配 逐条入库、逐条转换
streamArray + data 事件写,不处理背压 同上 407MB 约 10s 反面教材
streamArray + write()/drain 背压 同上 161MB 约 10s 解析结果落盘/转发

环境说明:Node 22.13、/usr/bin/time -v 量 Maximum resident set size,样本为合成数据(字段结构仿真实业务),单次运行非重复均值;慢写库是 setTimeout 模拟。数字是这份样本的量级结论,不是通用常数——换自己的样本量才是规矩。

值得注意的两个读数:第一种与第二种差 6 倍内存,代价是耗时从「1.3 秒」变成「跟着数据库走」;第三、四种差 2.5 倍,说明读侧流式了、写侧不配背压,等于白流一半。

六、排查:怎么确认背压真的在工作

线上内存问题不能全靠猜。腾讯云社区一篇背压排查文给出的定位手法很实用:

  1. 在关键流上临时挂 'pause' 和 'resume' 日志。一条大流量链路如果从未出现过 pause,而数据量又大,基本可以断定有地方把数据攒在内存里了;
  2. 看 writable.writableLength(写缓冲字节数),持续增长就是不消化;
  3. 用 process.memoryUsage() 定时采样 RSS 画曲线,区分「爬坡式增长」(攒数据)与「锯齿式平稳」(正常回收)。

for await 语义下这两条日志一定交替出现;如果完全没有,检查是不是混进了 data 事件监听或忘了 await。

七、什么时候不需要流式

流式不是默认答案。文件几十 MB 以内、又需要按 key 随机访问,JSON.parse 一次到位反而更省事;浏览器端打开大文件看结构是另一个问题域,大文件 JSON 怎么打开 一文讲的是查看器的选型阶梯。流式解析的适用边界很清楚:

  • 顶层是数组(或可用 JSONL 逐行切开),消费模式是「逐条处理」,不需要回头引用前文;
  • 文件大小不可控或远超堆余量,进程不能为一次导入翻倍内存;
  • 消费端有天然速度差(写库、写下游接口),需要背压而不是全速灌。

顶层结构不规整(对象套数组、多文档混合)时,先在 JSON 解析格式化 页面看一眼结构再选读法;命令行侧的处理路径在 jq 处理大 JSON 一文,jq --stream 与本篇的 streamArray 是同一个思路在两种运行时的落地。

常见问题

stream-json 和 JSON.parse 性能差多少?

纯解析速度 JSON.parse 更快:186MB 样本 1.3 秒,streamArray 无写入延迟时约 7 秒(token 级解析 + 对象逐条构建的开销)。流式的收益全部在内存侧:峰值从 612MB 降到 104MB。导入任务写库才是瓶颈,解析多花几秒换内存 6 倍的余量,通常是笔划算账;毫秒级接口响应里用流式则不合适。

for await 的背压和手动 pause/resume 是一回事吗?

语义等价:for await 在迭代体未完成时自动暂停可读流,等价于你手动在 write() 返回 false 时调 pause() 并在 drain 时 resume()。区别在于 for await 把这件事交给了语言机制,不会漏;手动写法一旦漏掉一处,整条链路背压就断了。

顶层不是数组,是一个大对象怎么办?

stream-json 提供 streamObject()(逐键抛出)与 Pick 过滤器(只解析指定路径子树)。如果只需要对象里某几个字段,用 Pick 配 JSONPath 能把「全量对象图」缩成「需要的子图」。多文档混合(多行 JSON、JSON Seq)则建议先拆行,逐行当独立 JSON 处理。

需要把结果写成 JSONL 或转发给下游接口怎么办?

写侧同样是背压问题:fs.createWriteStream 或 http.request 都要检查 write() 返回值,false 就 await once(stream, 'drain');或者直接把写流接进 pipeline(),让 Node 替你管理。验证方法很简单:跑一遍后看 RSS 曲线是否平稳,再抓一次写流的 writableLength 确认没有持续增长。

怎么快速给导入任务加内存监控?

最小方案是定时器每 100ms 采一次 process.memoryUsage().rss 存进数组,任务结束时取最大值并打印;要更准用 /usr/bin/time -v node task.js 直接看 Maximum resident set size。容器里再把告警线设在容器内存限额的 70%,给 GC 留余量。

参考资料

同系列工具

相关文章

jq 处理大文件 JSON:-s 为什么爆内存,流式怎么写

几百 MB 的 JSON 日志用 jq -s 聚合直接被系统杀掉,换成 reduce inputs 后同样的统计内存只要几 MB。本文用 220MB、200 万行样本实测两种写法的耗时与内存峰值,讲清 -s 和整体解析吃内存的机制、JSONL 逐行处理的正道、--stream 路径事件的写法,以及 -n --stream 静默零输出等三个真实的坑。

实战约 6 分钟更新于 2026-11-12

JSON 的内存账:字符串、对象与大数组各占多少

一份 10MB 的 JSON 文本,解析后可能变成三到五倍大小的对象图,峰值还要再翻一倍。本文把字符串、对象、数组与数字在 V8 里的实际开销逐项拆开,给出用 process.memoryUsage 做基线测量的方法,并说明流式解析到底省在哪一段内存。

实战约 11 分钟更新于 2026-10-31

大文件 JSON 打不开怎么办:按体积选对工具

几十 MB 的 JSON 导出在文本编辑器和在线工具里经常直接卡死,但解析本身只要几百毫秒。本文用一份 45MB、50 万条记录的样本实测各环节耗时与内存,解释行数和节点数才是真正的成本,并给出按文件体积选工具的决策表:在线查看、命令行提取、流式处理与桌面客户端各管一段。

实战约 6 分钟更新于 2026-11-07