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