JSON Toolkit

Große JSON-Dateien in Node.js lesen: Streaming-Parsing mit stream-json und Backpressure in der Praxis

Fazit: Ein 186MB JSON-Array mit readFileSync und JSON.parse zu lesen treibt den Speicher auf 612MB; mit dem streamArray von stream-json bleibt er konstant bei 104MB. Dieser Artikel vergleicht vier Lesestrategien mit Messwerten, erklärt, warum for await Backpressure gratis liefert, wie das data-Event sie verliert und wie man highWaterMark und drain auf der Schreibseite richtig einstellt.

Mittel~5 Min. LesezeitVeröffentlicht 2026-11-17Aktualisiert 2026-11-17
Streaming einer großen JSON-Datei in Node.js: Vergleich von streamArray und Backpressure

Wenn der Import einer 186MB-JSON-Datei den Prozess auf 600MB Speicher drückt, liegt es nicht an der Dateigröße — JSON.parse hat den ganzen Text in einem Zug gegen den ganzen Objektgraphen getauscht. Wechselt man die Lesestrategie, wird die Speicherkurve flach.

Ein Symptom: eine 186MB-Datei mit 612MB Peak

Serverseitige Importjobs sind das Hauptanwendungsgebiet dieses Problems: geplante Order-Syncs, Log-Bereinigung, Massenimporte historischer Daten. Die typische Implementierung sieht so aus:

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

Wir haben dieses Muster auf Node 22.13 gemessen. Das Beispiel: ein Objekt-Array mit 480.000 Bestelldatensätzen, Dateigröße 186MB, mit Strings, verschachtelten Objekten und Arrays in den Feldern, um echte Geschäftsstrukturen nachzubilden. Peak des Maximum resident set size gemessen mit /usr/bin/time -v: Die Datei liest sich in 1.3 Sekunden, aber der RSS erreicht 612MB — das 3.3-fache der Datei. Bei der Standardgrenze des Old Space von V8 mit 1.4–2GB reichen wenige solche Jobs parallel aus, um im Container per OOM Kill zu enden.

Die Rechnung ist nicht exotisch: Der Rohtext belegt eine Kopie im Speicher (etwa 186MB), der geparste Objektgraph eine zweite (jeder String-Schlüssel, jeder Kopf eines verschachtelten Objekts und jedes Arrays kostet zusätzlich), und der Parsing-Prozess selbst allokiert vorübergehend obendrauf. 600MB Peak sind normal.

Zweite Ursache: JSON.parse tauscht ganzen Text gegen ganzen Graphen

Der Vertrag von JSON.parse lautet: „Gib mir den vollständigen Text, du bekommst den vollständigen Objektgraphen." Er verlangt, dass der gesamte Text vor dem Start bereitliegt, und übergibt das Ergebnis erst nach Abschluss. Es gibt keinen Mechanismus für „hier erst mal die ersten 1.000 Datensätze".

Die Kosten des Objektgraphen wurden in Die Speicherbilanz von JSON Posten für Posten gemessen: Jeder String belegt echten Platz, jeder Objekt-Schlüssel einen Slot, und die Breite eines Arrays hängt von den Elementtypen ab. Ein paar Dutzend MB JSON werden nach dem Parsing regelmäßig drei- bis fünfmal größer, der Peak kommt obendrauf.

Die meisten Importjobs brauchen den ganzen Graphen jedoch nie: zeilenweise einfügen, zeilenweise filtern, zeilenweise transformieren — jeder Datensatz kann direkt nach der Verarbeitung freigegeben werden. Was der Job braucht, ist „einen Datensatz parsen, einen Datensatz ausliefern". Genau das ist die Definition des Streaming-Parsings.

Die Lösung: streamArray konsumiert Datensatz für Datensatz, und for await liefert Backpressure gratis

stream-json implementiert den Parser als Transform-Stream, der Token konsumiert und nie auf die ganze Datei wartet. Ist die oberste Ebene ein Array, gibt streamArray() in dem Moment {key, value} aus, in dem jedes Element fertig geparst ist:

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);
  }
}

Auf derselben 186MB-Datei mit denselben 480.000 Datensätzen erreicht diese Version einen RSS-Peak von 104MB, über die gesamte Laufzeit flach. Im Speicher existieren jederzeit nur „das aktuelle Element + der Parserzustand"; fertige Datensätze werden sofort freigegeben.

Ein leicht zu übersehendes Detail: for await zieht den nächsten Datensatz nicht vom Parser, bevor saveToDb abgeschlossen ist, sodass der Parser das Lesen der Datei unterbricht. Langsamere Datenbank, langsamereres Lesen — das ist Backpressure, natürlich entstanden, ohne eine Zeile Extra-Code. Ein dev.to-Bericht über die Aufnahme eines kommunalen 4GB-Feeds nutzt dieselbe Kette mit pick({filter:'data'}) und meldet eine ebenso flache Speicherkurve.

Wenn die Schreibseite versagt: ein nicht pausierendes data-Event drückt den Speicher wieder hoch

Streaming-Parsing diszipliniert nur die Leseseite. Nimmt die Schreibseite keine Backpressure an, steigt der Speicher wieder. Der klassische Fehler: asynchrones Schreiben in einem data-Handler ohne Blick auf den Puffer des Writables:

// Falsch: data-Event + asynchrones Schreiben, Backpressure komplett verloren
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // der Stream wartet nicht; der Puffer schwillt weiter
});

Im data-Modus fließt der Stream weiter, egal wie langsam slowWrite ist, und alles stapelt sich im internen Puffer des Writables. Auf derselben 186MB-Stichprobe leiteten wir die Datensätze in einen langsamen Writable um, der jeden hundertsten Chunk um 1ms verzögert. Ohne Backpressure-Handling erreichte der RSS-Peak 407MB; mit await once(sink, 'drain'), wenn write() false zurückgibt, 161MB. Die Differenz von 246MB sind buchstäblich Daten, die im Schreibpuffer sitzen.

// Richtig: pausieren, wenn write() false zurückgibt, weiter bei drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Zwei Praxisnotizen: Beim manuellen Zusammenbau von Stream-Ketten highWaterMark für jeden Stream explizit setzen — der Standardwert von 16 in objectMode ist für große Objekte zu großzügig; und pipeline() aus stream/promises statt pipe() bevorzugen, das Fehlerausbreitung und Aufräumen übernimmt.

Die Messwerte: Peak-Speicher von vier Strategien

Strategie Stichprobe Peak RSS Dauer Einsatz
readFileSync + JSON.parse 186MB / 480k 612MB 1.3s kleine Dateien, wahlfreier Zugriff
streamArray + for await + langsame DB-Schreibvorgänge (je 0.5ms) dieselbe 104MB (flach) tempo der DB satzweiser Import, Transformationen
streamArray + data-Event-Schreibvorgänge ohne Backpressure dieselbe 407MB ~10s Negativbeispiel
streamArray + write()/drain dieselbe 161MB ~10s Ausgabe auf Datenträger oder weiterreichen

Umgebung: Node 22.13, Maximum resident set size aus /usr/bin/time -v, synthetische Stichprobe mit geschäftsähnlichen Feldern, Einzelläufe ohne Mittelung, simulierte langsame Schreibvorgänge via setTimeout. Diese Zahlen sind Größenordnungs-Aussagen für diese Stichprobe, keine universellen Konstanten — messen Sie mit Ihren eigenen Daten.

Zwei Werte verdienen Aufmerksamkeit. Die erste und die zweite Strategie unterscheiden sich um das Sechsfache an Speicher, zum Preis eines Tauschs von „1.3 Sekunden" gegen „so schnell wie die DB". Die dritte und die vierte unterscheiden sich um das 2.5-fache: Streaming-Lesen ohne Backpressure beim Schreiben löst nur die halbe Aufgabe.

Diagnose: prüfen, ob Backpressure wirklich arbeitet

Speicherprobleme in Produktion löst man nicht nach Gefühl. Ein Tencent-Cloud-Artikel zur Backpressure-Fehlersuche liefert ein praktisches Vorgehen:

  1. Loggen Sie vorübergehend 'pause'- und 'resume'-Events auf den kritischen Streams. Wenn ein Pipeline mit hohem Durchsatz nie pausiert, häufen sich irgendwo Daten im Speicher;
  2. Beobachten Sie writable.writableLength — stetiges Wachstum heißt, der Puffer entleert sich nie;
  3. Samplen Sie den RSS mit process.memoryUsage() in Intervallen und zeichnen Sie die Kurve, wobei Sie „rampenartiges Wachstum" (Ansammlung) von „sägezahnartiger Stabilität" (gesunde Freigabe) unterscheiden.

Unter for await-Semantik müssen sich die Pause- und Resume-Events abwechseln; wenn sie nie feuern, suchen Sie nach einem überzähligen data-Listener oder einem fehlenden await.

Wann Streaming nicht die Antwort ist

Streaming ist nicht die Standardlösung. Bei Dateien von wenigen Dutzend MB mit wahlfreiem Zugriff per Schlüssel ist ein einzelner JSON.parse-Aufruf einfacher und billiger. Das Öffnen großer Dateien im Browser ist ein anderes Problemfeld — wie man eine große JSON-Datei öffnet behandelt die Viewer-Leiter. Die Grenzen des Streaming-Parsings sind klar:

  • die oberste Ebene ist ein Array (oder die Daten lassen sich als JSONL zeilenweise teilen), der Konsum ist sequenziell, ohne Rückblick;
  • die Dateigröße ist unkontrolliert oder übersteigt den Heap-Rand deutlich, und ein Import darf den Fußabdruck des Prozesses nicht verdoppeln;
  • der Konsument hat ein natürliches Geschwindigkeitsgefälle (DB-Schreibvorgänge, Downstream-API-Aufrufe), also braucht es Backpressure statt Vollgas-Schlauch.

Wenn die Form der obersten Ebene unregelmäßig ist, sehen Sie sich die Struktur zuerst im JSON-Parser und -Formatierer an; das Kommandozeilen-Äquivalent behandelt jq für große JSON — jq --stream und streamArray sind dieselbe Idee in zwei Runtimes.

FAQ

Wie viel langsamer ist stream-json als JSON.parse?

Beim reinen Parsing gewinnt JSON.parse: 1.3 Sekunden für die 186MB-Stichprobe gegenüber etwa 7 Sekunden für streamArray ohne Schreibverzögerung (Token-Parsing plus objektweiser Aufbau). Der Nutzen des Streamings liegt vollständig auf der Speicherseite: der Peak fällt von 612MB auf 104MB. Ein Import ist ohnehin durch die Datenbank begrenzt, also sind ein paar Sekunden mehr Parsing für den sechsfachen Speicher-Puffer meist ein guter Deal; innerhalb von API-Antworten im Millisekundenbereich nicht.

Ist die Backpressure von for await dasselbe wie manuelles pause/resume?

Semantisch ja: for await pausiert den lesbaren Stream, solange der Schleifenkörper aussteht, was dem Aufruf von pause() entspricht, wenn write() false zurückgibt, und resume() bei drain. Der Unterschied: die Sprachmechanik übernimmt die Buchführung und vergisst nichts; manuelle Verkabelung verliert die Backpressure der ganzen Kette, sobald eine Stelle fehlt.

Was, wenn die oberste Ebene ein einziges riesiges Objekt ist?

stream-json liefert streamObject() (gibt pro Schlüssel aus) und den Pick-Filter (parst nur den gewählten Teilbaum). Wenn einige Felder genügen, schrumpft Pick mit JSONPath den ganzen Graphen auf den benötigten Teilgraphen. Mehrdokumenteneingaben (JSON Lines, JSON-Sequenzen) teilt man besser zeilenweise und verarbeitet sie als unabhängige Dokumente.

Wie schreibe ich das Ergebnis als JSONL oder leite es weiter?

Die Schreibseite stellt dieselbe Backpressure-Frage: fs.createWriteStream und http.request verlangen, den Rückgabewert von write() zu prüfen und bei false auf once(stream, 'drain') zu warten — oder den Writable in pipeline() einhängen. Die Kontrolle ist einfach: Die RSS-Kurve nach einem Lauf muss stabil sein und writableLength darf nicht dauerhaft wachsen.

Was ist der schnellste Speichermonitor für einen Importjob?

Minimalversion: ein Timer, der alle 100ms process.memoryUsage().rss in ein Array sampelt und am Ende das Maximum druckt. Präziser: /usr/bin/time -v node task.js liefert direkt den Maximum resident set size. In Containern legt man die Alarmlinie auf 70% des Speicherlimits, um dem GC Spielraum zu lassen.

Quellen

Passende Tools

Verwandte Artikel

jq und große JSON-Dateien: Warum -s den Speicher sprengt und wie man streamt

Die Aggregation von Hunderten MB JSON-Logs mit jq -s endet im OOM, während reduce inputs dieselbe Statistik mit wenigen MB RAM erzeugt. Gemessen an einer 220-MB-Stichprobe mit 2 Millionen Zeilen: slurp gipfelt bei 2,08 GB gegenüber 3,5 MB für den Streaming-Reducer. Dieser Artikel erklärt den Speichermechanismus, die zeilenweise JSONL-Verarbeitung, die Pfadereignisse von --stream und drei echte Fallstricke, darunter die stille Leer-Ausgabe von -n --stream.

Fortgeschritten~6 Min. LesezeitAktualisiert 2026-11-12

Große JSON-Datei öffnet nicht? Das richtige Werkzeug nach Größe wählen

JSON-Exporte im Bereich von Dutzenden MB lassen Texteditoren und Online-Tools häufig einfrieren, obwohl das Parsen nur wenige Hundert Millisekunden dauert. Wir haben an einer 45-MB-Stichprobe mit 500.000 Datensätzen Zeit und Speicher jeder Stufe gemessen, gezeigt, dass Zeilen- und Knotenzahl die wahren Kosten sind, und eine Entscheidungstabelle je Dateigröße erstellt: Online-Ansicht, Kommandozeilen-Extraktion, Streaming und Desktop-App.

Mittelstufe~6 Min. LesezeitAktualisiert 2026-11-07