Der komplette Leitfaden zur URL-Kodierung: Wann encodeURIComponent (und wann nicht)

Tippen Sie eine URL mit Leerzeichen oder nicht-englischen Zeichen in die Adressleiste eines Browsers, drücken Sie Enter, und sehen Sie zu, wie sie sich in etwas wie %E4%B8%AD%E6%96%87 verwandelt. Das ist URL-Kodierung — auch Prozentkodierung genannt —, und fast jeder Webentwickler wurde davon schon gebissen: Query-Parameter, die als verstümmelter Text am Server ankommen, verirrte %25-Sequenzen vom doppelten Dekodieren oder ein einzelnes &-Zeichen, das eine ganze Parameterliste zerstört. Diese Anleitung erklärt, wie URL-Kodierung wirklich funktioniert, und gibt Ihnen ein klares Regelwerk: wann kodieren, welche Funktion nutzen und wann Dinge in Ruhe lassen.

Warum URLs überhaupt Kodierung brauchen

URLs wurden entworfen, um mit dem reinen ASCII-Zeichensatz geschrieben und übertragen zu werden. Doch eine URL muss zwei Aufgaben zugleich erfüllen: Sie enthält Strukturzeichen (:, /, ?, &, =, #), die ihr Bedeutung geben, und sie transportiert beliebige Daten. Der Konflikt ist offensichtlich — enthält ein Parameterwert selbst ein &, wie soll ein Parser wissen, ob es ein Trenner oder Teil der Daten ist? Kodierung löst das, indem sie Sonderzeichen innerhalb der Daten durch ein % plus zwei Hexadezimalziffern ersetzt, sodass sie nicht mehr als Struktur fehlgelesen werden können.

Reservierte vs. nicht reservierte Zeichen

RFC 3986 teilt Zeichen in zwei Lager. Nicht reservierte Zeichen — Buchstaben, Ziffern und -, _, ., ~ — sind überall in einer URL sicher und müssen nie kodiert werden. Reservierte Zeichen — : / ? # [ ] @ plus ! $ & ' ( ) * + , ; = — haben strukturelle Bedeutung, müssen also kodiert werden, wenn sie als Daten erscheinen, aber unangetastet bleiben, wenn sie ihre strukturelle Aufgabe tun.

Beachten Sie: Die Regel lautet „nach Rolle kodieren, nicht nach Zeichen.“ Dasselbe / ist ein legitimer Pfadtrenner, der so bleiben sollte, doch sobald es in einem Query-Parameterwert auftaucht, muss es %2F werden. Genau diese Unterscheidung ist der Grund, warum JavaScript zwei verschiedene Kodierungsfunktionen hat.

Warum Query-Parameter kodiert werden müssen

Ein konkretes Beispiel. Sagen wir, Sie wollen diesen Suchlink bauen:

https://example.com/search?q=Tom & Jerry&page=1

Hier stimmen zwei Dinge nicht: Leerzeichen sind in URLs illegal, und das & wird als Parameter-Trenner geparst. Der Server erhält q=Tom, einen leeren Parameter namens Jerry und page=1 — nichts wie beabsichtigt. Kodieren Sie den Wert, und das Problem verschwindet:

https://example.com/search?q=Tom%20%26%20Jerry&page=1

Das Leerzeichen wird %20, das & wird %26, und der Parser rekonstruiert korrekt Tom & Jerry. Wollen Sie ein kodiertes Ergebnis schnell gegenprüfen, fügen Sie den Text in den URL-Encoder ein — er bietet sowohl „vollständige URL“- als auch „Komponenten“-Modus, die direkt auf die beiden folgenden Funktionen abbilden.

encodeURI vs. encodeURIComponent

JavaScript liefert zwei Kodierungsfunktionen, und der Unterschied passt in einen Satz: encodeURI kodiert eine ganze URL; encodeURIComponent kodiert ein Stück einer URL.

encodeURI nimmt an, dass Sie ihm eine vollständige URL geben, lässt : / ? & = # also absichtlich in Ruhe. encodeURIComponent nimmt an, dass es einen einzelnen Wert bekommt, und kodiert fast alles außer den nicht reservierten Zeichen:

encodeURI('https://example.com/search?q=Tom & Jerry');
// https://example.com/search?q=Tom%20&%20Jerry
// Die strukturellen ? & = überleben — aber auch das & im Wert. Immer noch kaputt!

encodeURIComponent('Tom & Jerry');
// Tom%20%26%20Jerry

Die Faustregel: Nutzen Sie beim Bauen von Query-Strings immer encodeURIComponent:

const url = `https://example.com/search?q=${encodeURIComponent(keyword)}&page=${page}`;

encodeURI ist nur in einer Situation angemessen: Sie halten bereits eine vollständig zusammengesetzte, strukturell korrekte URL und wollen nur Nicht-ASCII-Zeichen und Leerzeichen bereinigen. Ein noch besserer moderner Ansatz ist URLSearchParams, das die Kodierung für Sie übernimmt:

const params = new URLSearchParams({ q: 'Tom & Jerry', page: '1' });
params.toString(); // q=Tom+%26+Jerry&page=1

%20 oder +: Eine kurze Geschichtsstunde

Vielleicht ist Ihnen aufgefallen, dass URLSearchParams das Leerzeichen als + kodiert, während encodeURIComponent %20 erzeugt. Beides ist korrekt — sie stammen nur aus verschiedenen Spezifikationen. Die +-Konvention kommt aus dem frühen HTML-Formularformat application/x-www-form-urlencoded (was eine GET-Formularübermittlung erzeugt), und Query-Strings erbten diese Tradition. %20 ist die RFC-3986-Standardprozentkodierung, gültig überall in einer URL.

Die praktische Konsequenz liegt auf der Dekodierungsseite: + bedeutet nur in einem Query-String- oder Formulardaten-Kontext „Leerzeichen“ — in einem Pfad ist + ein wörtliches Pluszeichen. Für Datei-Download-Links, deren Dateiname Leerzeichen enthält, ist %20 also die sicherere Wahl; innerhalb von Query-Parametern funktioniert beide Formen, und praktisch jeder Server akzeptiert beide. URLSearchParams und das URL-Objekt behandeln beide Formen korrekt, ein weiterer Grund, sie statt handgebauter Strings zu nutzen.

Doppelkodierung: Die klassische Falle

Doppelkodierung passiert, wenn bereits prozentkodierter Text erneut kodiert wird. Das % in %20 wird zu %25, aus einem Leerzeichen wird %2520. Der Server dekodiert einmal und erhält %20 statt eines Leerzeichens — die Grundursache hinter unzähligen verstümmelten Seiten, 404s und fehlgeschlagenen Signaturprüfungen.

Drei Szenarien lösen sie am häufigsten aus: Das Frontend kodiert einmal, und ein Framework (etwa bestimmte Routing-Bibliotheken) kodiert automatisch erneut; eine bereits kodierte URL aus location.href wird komplett in encodeURIComponent gesteckt; oder eine Proxy-Schicht wie Nginx oder ein CDN führt einen „hilfreichen“ Normalisierungslauf durch. Das Debuggen ist einfach: Suchen Sie die endgültige ausgehende URL nach %25 ab — ist es da, hat etwas zweimal kodiert. Die Lösung ist im Prinzip ebenso einfach: genau einmal kodieren, im letzten Schritt, und den Rohstring überall davor weiterreichen. Wird Ihnen eine verdächtige URL gereicht, zerlegt der URL-Parser sie in Schema, Host, Pfad und Query-Parameter, sodass Sie auf einen Blick sehen, welches Segment noch verirrte %-Sequenzen enthält.

Nicht-ASCII-URLs behandeln (Chinesisch, Emoji und Freunde)

Nicht-ASCII-Zeichen haben keine legale Form in einer URL. Sie müssen zuerst in eine UTF-8-Bytefolge umgewandelt werden, dann wird jedes Byte prozentkodiert. Da ein chinesisches Zeichen typischerweise drei UTF-8-Bytes braucht, wird 中 zu %E4%B8%AD. Moderne Browser-Adressleisten tun das automatisch — Sie können eine chinesische URL tippen, und es funktioniert einfach —, doch wenn Ihr Code die Anfrage stellt, sind Sie auf sich gestellt. Dieselbe Regel wie immer: encodeURIComponent für Werte, oder URLSearchParams machen lassen.

Ein verwandter Fall sind internationalisierte Domainnamen. Die nutzen gar keine Prozentkodierung; sie werden über Punycode in ASCII umgewandelt (das xn---Präfix, das Sie manchmal sehen), ein DNS-Mechanismus, der die Pfadkodierung nicht stört.

Und verwechseln Sie URL-Kodierung schließlich nicht mit Base64 — sie lösen verschiedene Probleme. URL-Kodierung beantwortet „kann dieses Zeichen in einer URL leben“, während Base64 beantwortet „wie stelle ich Binärdaten als druckbaren Text dar“. Manchmal stapeln Sie sie: Kodieren Sie ein Stück JSON zuerst als Base64 (der Base64-Encoder/Decoder ist praktisch zum Experimentieren), und URL-kodieren Sie dann die +, / und =, die Base64 erzeugen kann, bevor Sie das Ergebnis in einen Query-Parameter setzen. Haben Sie einmal verstanden, wofür jede Schicht da ist, verwechseln Sie sie nie wieder.

Kurzreferenz

Query-Strings bauen: URLSearchParams nutzen oder jeden Wert manuell mit encodeURIComponent kodieren;
Eine vollständige URL bereinigen: encodeURI — aber nur, wenn jeder Wert darin bereits kodiert war;
Dekodieren: decodeURIComponent auf einzelne Werte bevorzugen statt decodeURI auf die ganze URL;
Ein %25 zu entdecken heißt Doppelkodierung — finden Sie die Schicht, die einmal zu viel kodiert hat;
Leerzeichen in Dateinamen und Pfaden: %20 nutzen, nie +.