JSON escapen: So wird JSON zu einer einzeiligen Zeichenkette

VeröffentlichtToolJSON-Stringify & Escape-Tool

Inhalt
  1. Warum JSON in CLI-Argumenten oder .env-Werten ohne Escaping kaputtgeht
  2. Escapen von Hand, ohne Tool
  3. Häufige Missverständnisse
  4. Fazit
  5. Häufig gestellte Fragen

Wenn Sie mehrzeiliges JSON unverändert in ein CLI-Argument oder als Wert in eine .env-Datei einfügen, geht das schief, weil einige wenige Zeichen – Backslash, doppeltes Anführungszeichen und Zeilenumbruch – mit der Syntax des Ziels kollidieren.

Ersetzen Sie diese Zeichen jeweils durch die passende Escape-Sequenz, entsteht eine sichere einzeilige Zeichenkette, die den ursprünglichen Inhalt vollständig enthält. Dieser Artikel erklärt die Ersetzungsregeln Zeichen für Zeichen.

Zusammenfassung ① Fügen Sie JSON unverändert in ein CLI-Argument oder einen .env-Wert ein, kollidieren Backslash, doppelte Anführungszeichen und Zeilenumbrüche mit der Syntax des Ziels, und der Wert wird zerstört. ② Der Modus „JSON-Escape" prüft die Eingabe zunächst mit JSON.parse auf Gültigkeit und komprimiert sie dann auf eine Zeile. Der Modus „Rohtext-Escape" escapt die Eingabe ohne Prüfung unverändert. ③ Doppelte Anführungszeichen, Zeilenumbrüche und Tabs sind standardmäßig aktiviert, einfache Anführungszeichen standardmäßig deaktiviert. Ändern Sie die Kontrollkästchen, entsteht aus derselben Eingabe eine andere Zeichenkette.

Warum JSON in CLI-Argumenten oder .env-Werten ohne Escaping kaputtgeht

Stellen Sie sich vor, Sie kopieren JSON aus einer API-Antwort oder einer Konfigurationsdatei und fügen es in einer .env-Datei direkt hinter APP_CONFIG= ein. Das Original-JSON ist ein mehrzeiliger Text mit Zeilenumbrüchen und Einrückungen, damit er für Menschen gut lesbar ist.

Setzen Sie diesen Text dort ein, wo ein einzeiliger Wert erwartet wird, geht es an drei Stellen schief:

  • Zeilenumbruch: Eine .env-Datei oder eine Shell-Variable liest eine Zeile als einen Wert. Steht mitten im Wert ein echter Zeilenumbruch, endet der Wert in dieser Zeile.
  • Doppelte Anführungszeichen: Üblicherweise setzt man den gesamten Wert in doppelte Anführungszeichen, doch auch im JSON selbst stecken jede Menge davon. Sobald der Parser auf ein inneres Anführungszeichen trifft, deutet er den Wert als beendet.
  • CLI-Argument in einfachen Anführungszeichen: Steht in einem JSON-String-Wert ein Apostroph ('), lässt sich dieses in einer POSIX-Shell innerhalb einfacher Anführungszeichen nicht escapen. Das Argument wird an dieser Stelle geschlossen.

Deshalb stellen alle Ziele, in die JSON als einzeilige Zeichenkette gehört – CLI-Argumente, .env-Werte, String-Felder, die in einem anderen JSON verschachtelt sind, String-Literale im Quellcode –, dieselbe Anforderung:

Steuerzeichen wie Zeilenumbruch und Tab werden durch sichtbare Sequenzen ersetzt. Vor Anführungszeichen, die als Begrenzer dienen, und vor dem Backslash, der selbst fürs Escaping verwendet wird, kommt ein weiterer Backslash. Damit markieren Sie: „Dieses Zeichen ist kein Syntaxzeichen, sondern einfach Daten."

Escapen von Hand, ohne Tool

Die Escape-Regeln sind kein Geheimnis eines bestimmten Programms, sondern eine gemeinsame Ersetzungstabelle, der die meisten Sprachen folgen, darunter JSON.stringify.

Führen Sie den folgenden Code in der Konsole der Entwicklertools Ihres Browsers aus, können Sie das Ergebnis des hier beschriebenen Tools von Hand nachstellen.

So prüfen Sie die JSON-Syntax und komprimieren zugleich:

// Schritt 1: JSON-Syntax prüfen + auf eine Zeile komprimieren (Einrückungen und Zeilenumbrüche entfernen)
const minified = JSON.stringify(JSON.parse(rawInput));

// Schritt 2: Zeichen ersetzen. Der Backslash muss zuerst ersetzt werden,
// damit die danach hinzugefügten Backslashes nicht erneut ersetzt werden.
const escaped = minified
  .replace(/\\/g, "\\\\")  // Backslash → \\
  .replace(/"/g, '\\"')     // doppeltes Anführungszeichen → \" (optional)
  .replace(/\n/g, "\\n")    // Zeilenumbruch → \n (optional)
  .replace(/\t/g, "\\t");   // Tab → \t (optional)

Muss rawInput kein gültiges JSON sein – möchten Sie also etwa Log-Ausschnitte oder normalen Text unverändert escapen –, überspringen Sie Schritt 1 und wenden die Ersetzungskette aus Schritt 2 direkt auf die Originalzeichenkette an.

Genau das ist alles, was der Modus „Rohtext-Escape" tut.

Setzen Sie das so gewonnene Ergebnis in doppelte Anführungszeichen und fügen es als CLI-Argument oder .env-Wert ein, wird die Bedeutung des ursprünglichen JSON unverändert in einer Zeile übergeben.

Mit unserem JSON-Stringify & Escape-Tool ausprobieren.

JSON-Stringify & Escape-Tool

JSON wird nach der Prüfung per Parser auf eine Zeile komprimiert, normaler Text wird ohne Prüfung unverändert escapt. Kostenlos, ohne Installation und ohne Registrierung.

Häufige Missverständnisse

Der Unterschied zwischen den beiden Modi in der Übersicht:

MerkmalModus „JSON-Escape"Modus „Rohtext-Escape"
Prüfung mit JSON.parseJa (bei Fehler wird eine Fehlermeldung angezeigt)Nein
Komprimierung (Zeilenumbrüche und Einrückungen entfernen)Wird mit JSON.stringify komprimiertOriginal bleibt unverändert
Ungültige JSON-EingabeFehler „Kein gültiges JSON-Format"Wird ohne Fehler unverändert verarbeitet
AnwendungsbereichNur gültiger JSON-TextBeliebiger Text

Warum sich das Ergebnis beim Ein- und Ausschalten mancher Kontrollkästchen nicht ändert

Welche der vier Escape-Optionen das Ergebnis tatsächlich verändern, hängt vom Modus ab.

Im Modus „JSON-Escape" durchläuft die Eingabe zuerst einmal JSON.stringify. In diesem Schritt hat die JSON-Syntax selbst Zeilenumbrüche und Tabs innerhalb von String-Werten bereits in zweistellige Sequenzen wie \n und \t umgewandelt.

Deshalb ändern die nachgelagerten Kontrollkästchen „Zeilenumbrüche escapen" und „Tabulatoren escapen" im JSON-Modus das Ergebnis nicht, egal ob sie ein- oder ausgeschaltet sind. Es sind schlicht keine echten Zeilenumbruch- oder Tab-Zeichen mehr übrig, die ersetzt werden könnten.

Doppelte und einfache Anführungszeichen sowie der Rohtext-Modus verhalten sich anders

Dagegen wirkt „Doppelte Anführungszeichen escapen" auch im JSON-Modus. Die strukturellen doppelten Anführungszeichen um Schlüssel und Werte lässt JSON.stringify nämlich unverändert stehen.

Auch „Einfache Anführungszeichen escapen" betrifft ein Zeichen, das in der JSON-Syntax nicht vorkommt und das JSON.stringify daher nicht anfasst. Steht in einem Wert ein Apostroph, hängt das Ergebnis also vom Zustand des Kontrollkästchens ab.

Im Modus „Rohtext-Escape" läuft die Eingabe nicht durch JSON.stringify, sondern wird Zeichen für Zeichen unverändert durchsucht. Alle vier Optionen schlagen sich daher je nach Einstellung im Ergebnis nieder.

Beachten Sie außerdem: Der JSON-Modus serialisiert den von JSON.parse erzeugten Wert erneut mit JSON.stringify. Dadurch kann sich die Schreibweise des Originals leicht ändern, etwa wenn ein bedeutungsloses 1.0 zu 1 wird. Müssen Sie die Schreibweise buchstabengetreu erhalten, ist der Rohtext-Modus die sicherere Wahl.

Wenn die Fehlermeldung „Kein gültiges JSON-Format" erscheint

Diese Fehlermeldung erscheint, wenn JSON.parse die Eingabe nicht als JSON-Syntax interpretieren konnte. Häufige Ursachen sind:

  • Nach dem letzten Element steht noch ein Komma (Trailing Comma)
  • Schlüssel oder String-Werte stehen in einfachen Anführungszeichen (JSON erlaubt nur doppelte)
  • Schlüssel wurden ohne Anführungszeichen geschrieben
  • Es sind Kommentare (//, /* */) enthalten, die es in JSON nicht gibt
  • Die Anzahl öffnender und schließender Klammern stimmt nicht überein

Trifft einer dieser Punkte zu, erzeugt der JSON-Modus kein Ergebnis und zeigt nur den Fehler an. Möchten Sie die Syntax nicht korrigieren, wechseln Sie in den Modus „Rohtext-Escape". Dort wird die Eingabe ohne Prüfung unverändert escapt.

Fazit

  • Der Backslash wird immer escapt, doppelte Anführungszeichen, Zeilenumbrüche und Tabs standardmäßig, einfache Anführungszeichen nur, wenn Sie die Option aktivieren.
  • Der Modus „JSON-Escape" prüft mit JSON.parse und komprimiert zusätzlich. Dabei sind Zeilenumbrüche und Tabs in String-Werten aber schon zu \n und \t geworden, sodass die zugehörigen Kontrollkästchen im JSON-Modus wirkungslos sind.
  • Der Modus „Rohtext-Escape" durchsucht die Eingabe ohne Prüfung und ohne Komprimierung Zeichen für Zeichen. Alle vier Optionen wirken sich auf das Ergebnis aus, und er funktioniert auch bei Text, der kein JSON ist.
  • Die Fehlermeldung „Kein gültiges JSON-Format" hat ihre Ursache in Verstößen gegen die JSON-Syntax, etwa Trailing Commas, einfachen Anführungszeichen oder Schlüsseln ohne Anführungszeichen.
  • Dieselben Regeln lassen sich mit JSON.stringify und einer Kette von Regex-Ersetzungen selbst nachbauen.
JSON-Stringify & Escape-Tool

JSON wird nach der Prüfung per Parser auf eine Zeile komprimiert, normaler Text wird ohne Prüfung unverändert escapt. Kostenlos, ohne Installation und ohne Registrierung.

Häufig gestellte Fragen

Sollte ich JSON-Escaping oder Raw-Text-Escaping verwenden?

Wenn Ihre Eingabe gültiges JSON ist und Sie zugleich die Syntax prüfen und den Inhalt komprimieren möchten, verwenden Sie den Modus „JSON-Escaping".

Ist die Eingabe kein gültiges JSON (etwa ein Log-Ausschnitt, ein Teil eines Codes oder JSON mit Syntaxfehlern) oder möchten Sie die ursprünglichen Zeilenumbrüche und Einrückungen nur escapen, ohne sie zu komprimieren, verwenden Sie den Modus „Raw-Text-Escaping".

Im Ergebnis stehen jeweils zwei Backslashes hintereinander: ist das ein Fehler?

Nein, das ist kein Fehler. Eine Escape-Sequenz beginnt selbst immer mit einem Backslash ().

War in der Vorlage bereits ein Backslash enthalten, muss auch dieser escaped werden und wird zu \\. Wird zusätzlich das darauffolgende Zeichen (zum Beispiel ein doppeltes Anführungszeichen) escaped, können mehrere Backslashes direkt aufeinanderfolgen. Jeder dieser Backslashes steht für genau ein Escaping und ist ein korrektes Ergebnis.

Warum werden einfache Anführungszeichen standardmäßig nicht escaped?

Weil die JSON-Syntax Zeichenketten ausschließlich in doppelte Anführungszeichen setzt und einfachen Anführungszeichen keinerlei Bedeutung zuweist.

Deshalb sind doppelte Anführungszeichen, Zeilenumbrüche und Tabulatoren standardmäßig aktiviert. Einfache Anführungszeichen werden dagegen nur für bestimmte Zielumgebungen benötigt, etwa für Shell-Skripte, in denen der Wert in einfache Anführungszeichen gesetzt wird. Deshalb ist diese Option standardmäßig deaktiviert. Bei Bedarf aktivieren Sie einfach das Kontrollkästchen.

Muss ich die Anführungszeichen selbst setzen, wenn ich das Ergebnis in eine .env-Datei oder als CLI-Argument einfüge?

Ja. Das JSON-Stringify & Escape-Tool ersetzt nur die Zeichen innerhalb der Zeichenkette und fügt keine äußeren Anführungszeichen um den gesamten Wert hinzu. Wenn Sie das Ergebnis in eine .env-Datei oder als CLI-Argument einfügen, müssen Sie es selbst in doppelte (oder einfache) Anführungszeichen setzen, damit es als ein einziger Wert erkannt wird.

Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen

Ähnliche Artikel

  1. Verschachteltes JSON verflachen: Regeln für das Verbinden von SchlüsselnSo werden verschachtelte JSON-Schlüssel beim Verflachen zusammengesetzt, warum Arrays unverändert bleiben und welche Trennzeichen beim Entfalten Fehler verursachen.
  2. JSON-Schlüssel von camelCase in snake_case umwandelnSo wandeln Sie JSON-Schlüssel zwischen camelCase, snake_case, PascalCase und kebab-case um – auch in verschachtelten Objekten und Arrays – samt Sonderfällen.
  3. JSON-Schlüssel löschen: Mehrere Eigenschaften rekursiv entfernenSo entfernen Sie mehrere JSON-Schlüssel per Komma-Liste rekursiv in einem Schritt – inklusive Groß-/Kleinschreibung, exakter Übereinstimmung und ungültigem JSON.
  4. JSON Schlüssel sortieren: Was die Sortierung tatsächlich ändertJSON-Schlüssel alphabetisch sortieren: Die Reihenfolge im Array bleibt erhalten. Beispiele zeigen, wie rekursive Option und Einrückung das Ergebnis beeinflussen.
  5. JavaScript-Objekt in JSON umwandeln: Fehlerursachen und LösungWarum JSON.parse bei kopierten JS-Objekten „Unexpected token“ meldet, was JSON-Syntax von Objektliteralen unterscheidet und wie Sie in der Konsole konvertieren.
  6. JSON-Schema erstellen: So werden Typen erkannt (Draft-07)Wie aus einem JSON-Beispiel ein Draft-07-Schema entsteht: Typerkennung bei Strings, Zahlen und Arrays, required und anyOf erklärt, plus Grenzen eines Beispiels.

Passende Tools