Node.js 讀大 JSON:stream-json 串流解析與背壓實戰
結論:186MB 的 JSON 陣列用 readFileSync 加 JSON.parse 讀,峰值記憶體 612MB;換成 stream-json 的 streamArray 逐條消費,記憶體恆定在 104MB。本文給出四種讀法的實測對照,講清 for await 為什麼天然背壓、data 事件怎麼把背壓弄丟、寫入側該怎麼配 highWaterMark 與 drain。

匯入一個 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 倍,說明讀側串流了、寫側不配背壓,等於白流一半。
六、排查:怎麼確認背壓真的在工作
線上記憶體問題不能全靠猜。騰訊雲社區一篇背壓排查文給出的定位手法很實用:
- 在關鍵串流上臨時掛
'pause'和'resume'日誌。一條大流量鏈路如果從未出現過 pause,而資料量又大,基本可以斷定有地方把資料攢在記憶體裡了; - 看
writable.writableLength(寫緩衝位元組數),持續增長就是不消化; - 用
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 留餘量。