URL-Kodierung erklärt: Prozent-Kodierung in HTTP-Anfragen

URLs sehen von außen einfach aus — eine Zeichenkette, die auf eine Ressource verweist. Darunter folgen sie jedoch einer strikten Grammatik, die nur eine bestimmte Menge von Zeichen erlaubt. Sobald Sie ein Leerzeichen, ein kaufmännisches Und oder ein Nicht-ASCII-Zeichen ohne Kodierung in eine URL einbetten, entstehen Fehler, die schwer zu debuggen sind. Die Prozent-Kodierung (allgemein URL-Kodierung genannt) ist der Mechanismus, der beliebige Daten sicher in einer URL unterbringbar macht.

URLs können Sie sofort mit dem BrowseryTools URL-Encoder/Decoder kodieren und dekodieren — kostenlos, ohne Anmeldung, alles läuft in Ihrem Browser.

Warum Sonderzeichen URLs beschädigen

Die URL-Spezifikation (RFC 3986) reserviert bestimmte Zeichen für strukturelle Zwecke. Das ? trennt den Pfad vom Query-String. Das & trennt Query-Parameter voneinander. Das # markiert einen Fragment-Bezeichner. Der / trennt Pfadsegmente. Enthält Ihre Datenpayload eines dieser Zeichen, kann ein URL-Parser nicht unterscheiden, ob es sich um Ihre Daten oder die URL-Struktur selbst handelt.

Betrachten Sie eine Suchanfrage nach rock & roll. Die naive Konstruktion der URL ergibt:

/search?q=rock & roll
          ^     ^
          |     └── looks like a new parameter begins here
          └── this & splits q from a phantom second parameter

Der Parser liest q=rock (mit nachfolgendem Leerzeichen) als ersten Parameter und stößt dann auf den Beginn eines zweiten Parameters namens roll. Beide Werte sind falsch. Die korrekte URL lautet /search?q=rock%20%26%20roll — das Leerzeichen wird zu %20 und das kaufmännische Und zu %26.

Was Prozent-Kodierung tatsächlich bewirkt

Die Prozent-Kodierung wandelt ein Byte in eine dreistellige Zeichenfolge um: ein Prozentzeichen gefolgt von zwei großgeschriebenen Hexadezimalziffern, die den Bytewert darstellen. Das Leerzeichen (ASCII-Byte 32, Hex 0x20) wird zu %20. Das At-Zeichen (@, ASCII 64, Hex 0x40) wird zu %40. Die Regel lautet:

percent-encode(byte) = "%" + byte.toString(16).toUpperCase().padStart(2, "0")

Examples:
  space  (0x20) → %20
  @      (0x40) → %40
  [      (0x5B) → %5B
  €      (UTF-8: 0xE2 0x82 0xAC) → %E2%82%AC

Bei Multi-Byte-Unicode-Zeichen (alles außerhalb von ASCII) wird das Zeichen zunächst in UTF-8-Bytes kodiert, und jedes Byte wird anschließend prozent-kodiert. Das Eurozeichen € besteht aus drei UTF-8-Bytes und wird daher zu drei Prozent-kodierten Sequenzen: %E2%82%AC.

Sichere Zeichen vs. reservierte Zeichen

Nicht jedes Zeichen muss kodiert werden. RFC 3986 definiert zwei Gruppen, die unverändert verwendet werden dürfen:

• Nicht reservierte Zeichen — A–Z, a–z, 0–9, Bindestrich, Unterstrich, Punkt, Tilde. Diese haben keine besondere Bedeutung und müssen nie kodiert werden.
• Reservierte Zeichen — : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Diese sind in ihrer strukturellen Position sicher, müssen aber kodiert werden, wenn sie als Datenwerte auftreten.

Alles andere — Leerzeichen, Unicode, Steuerzeichen, die meisten Sonderzeichen — muss immer kodiert werden.

encodeURI vs. encodeURIComponent: Der entscheidende Unterschied

JavaScript verfügt über zwei eingebaute Kodierungsfunktionen, und ihre Verwechslung ist einer der häufigsten URL-Kodierungsfehler in Webanwendungen.

encodeURI() ist dafür ausgelegt, eine vollständige URL zu kodieren. Reservierte Zeichen werden unverändert gelassen, da sie in einer vollständigen URL strukturell bedeutsam sind. Sie würden diese Funktion verwenden, wenn Sie eine vollständige URL haben, die Leerzeichen oder Unicode enthält, aber eine gültige Struktur aufweist:

encodeURI("https://example.com/search?q=hello world&lang=en")
// → "https://example.com/search?q=hello%20world&lang=en"
//   ✓ space encoded, but & and ? left intact

encodeURIComponent() ist dafür ausgelegt, einen einzelnen Wert zu kodieren — einen Query-Parameter-Wert, ein Pfadsegment, alles, was als reine Datenpayload behandelt werden muss. Auch reservierte Zeichen werden kodiert, einschließlich &, =, ? und /:

encodeURIComponent("rock & roll")
// → "rock%20%26%20roll"
//   ✓ & encoded — safe to use as a query parameter value

encodeURIComponent("https://example.com/page")
// → "https%3A%2F%2Fexample.com%2Fpage"
//   ✓ colons and slashes encoded — safe as a redirect_uri value

Die Faustregel: Beim Aufbau einer URL verwenden Sie encodeURIComponent() für jeden einzelnen Parameterwert, niemals für die gesamte URL. Verwenden Sie encodeURI() nur auf einer vollständigen URL, die Sie normalisieren möchten. In modernem Code bevorzugen Sie die URL- und URLSearchParams-APIs gegenüber manueller Kodierung — diese übernehmen die Kodierung automatisch und korrekt.

Fallstricke bei der Query-String-Kodierung

Beim Kodieren von Query-Strings treten wiederholt subtile Fehler auf. Das Pluszeichen + verdient besondere Erwähnung: Im Format application/x-www-form-urlencoded (dem Format, mit dem HTML-Formulare übermittelt werden) wird ein Leerzeichen als + statt als %20 kodiert. Dies ist eine veraltete Konvention, die älter als RFC 3986 ist. Wenn Ihr Backend URL-Dekodierung gemäß Form-Kodierungsregeln durchführt und das Frontend %20 sendet, funktioniert es. Sendet das Frontend jedoch + und das Backend dekodiert nach RFC 3986, bleibt das + als wörtliches Pluszeichen erhalten — kein Leerzeichen.

// URLSearchParams uses application/x-www-form-urlencoded (+ for spaces)
new URLSearchParams({ q: "rock & roll" }).toString()
// → "q=rock+%26+roll"

// encodeURIComponent uses RFC 3986 (%20 for spaces)
"q=" + encodeURIComponent("rock & roll")
// → "q=rock%20%26%20roll"

// Both are valid — just be consistent on both ends

Wie Formulardaten URL-kodiert werden

Wenn ein HTML-Formular mit method="GET" abgesendet wird, serialisiert der Browser die Formularfelder mithilfe von application/x-www-form-urlencoded in einen Query-String. Jeder Feldname und -wert wird kodiert (Leerzeichen als +, Sonderzeichen als %XX), und Felder werden mit & verknüpft. Bei method="POST"-Formularen ohne enctype-Attribut wird dieselbe Kodierung verwendet, die Daten landen jedoch im Request-Body statt in der URL.

Dies ist auch das Format, das fetch() verwendet, wenn Sie ein URLSearchParams-Objekt als Body übergeben, und es wird von den meisten serverseitigen Frameworks beim Lesen von Formularübermittlungen automatisch dekodiert.

Base64 in URLs

Standard-Base64 verwendet + und / — beide haben in URLs eine besondere Bedeutung. Wenn Base64-kodierte Daten in einer URL erscheinen müssen (ein gängiges Muster für Tokens, Bilddaten oder kryptografische Signaturen), verwenden Sie stattdessen die Base64URL-Variante. Sie ersetzt + durch - und / durch _ und erzeugt so eine Zeichenkette, die in jeder URL-Position ohne weitere Kodierung sicher ist. JWTs verwenden dieses Format für ihre Header- und Payload-Segmente.

Reale Kodierungsfehler

Einige Fehlermuster, die in Produktionsanwendungen immer wieder auftreten:

• Doppelte Kodierung — eine bereits kodierte URL erneut kodieren. %20 wird zu %2520, weil % selbst zu %25 kodiert wird. Prüfen Sie immer, ob ein Wert bereits kodiert ist, bevor Sie ihn erneut kodieren.
• Fehlende encodeURIComponent bei redirect_uri — OAuth-Flows übergeben eine redirect_uri als Query-Parameter. Enthält diese ein ? oder & und ist nicht kodiert, parst der Auth-Server diese Zeichen als Teil der äußeren URL-Struktur und bricht die Weiterleitung.
• Nicht-UTF-8-Kodierung — ältere Systeme oder falsch konfigurierte Server kodieren Zeichenketten manchmal mit ISO-8859-1 statt UTF-8. Die Bytefolge für é unterscheidet sich zwischen beiden. Setzen Sie UTF-8 auf beiden Seiten konsequent durch.
• Rohe URLs protokollieren — das Protokollieren einer URL mit kodierten Nutzerdaten kann irreführende Logs erzeugen, wenn Ihr Log-Viewer Prozentsequenzen automatisch dekodiert und so verbirgt, was tatsächlich auf der Leitung gesendet wurde.

URLs sofort kodieren und dekodieren

Ob Sie einen OAuth-Redirect debuggen, einen Query-String manuell aufbauen, eine fehlerhafte API-Anfrage untersuchen oder einfach verstehen möchten, was eine prozent-kodierte URL enthält — der BrowseryTools URL-Encoder/Decoder erledigt das sofort. Fügen Sie Ihre Zeichenkette ein, wählen Sie Kodieren oder Dekodieren, und sehen Sie das Ergebnis unmittelbar. Keine Serveraufrufe, keine Anmeldung.