URL-Kodierung erklärt: Prozentkodierung und wo sie beißt

Die Regel gilt pro Komponente, nicht pro URL

Eine URL ist keine einzelne Zeichenkette, sondern eine Folge benannter Teile: Schema, Host, Pfad, Query, Fragment. Jeder Teil hat seine eigene Vorstellung davon, was Struktur und was Daten sind, und Prozentkodierung existiert, um beides auseinanderzuhalten. Ein Schrägstrich im Pfad ist Struktur — er trennt Segmente — und bleibt daher stehen. Derselbe Schrägstrich in einem Query-Wert ist Daten und muss %2F geschrieben werden, sonst hat ein Parser der Query keine Möglichkeit zu erkennen, dass du ein wörtliches Zeichen meintest und nicht ein verirrtes Stück Pfad.

Die Folge zeigt sich, sobald du eine URL durch Verkettung baust. Angenommen, ein Dateiname lautet 2026/08 report.pdf und soll in ein Pfadsegment. Kodierst du den Wert, erhältst du /files/2026%2F08%20report.pdf, ein Segment wie beabsichtigt. Lässt du die Kodierung weg, erhältst du /files/2026/08 report.pdf, drei Segmente und ein Leerzeichen, das auf etwas zeigt, das es nicht gibt. Dieselbe Asymmetrie trifft Query-Werte: ?note=rock&roll wird als zwei Parameter gelesen, note mit dem Wert rock und ein leeres roll, während ?note=rock%26roll als der eine Wert gelesen wird, den du meintest.

Reserviert und unreserviert, genau wie RFC 3986 sie definiert

Die unreservierte Menge ist klein und lohnt das Auswendiglernen: die Buchstaben A bis Z in beiden Schreibweisen, die Ziffern 0 bis 9 und genau vier Satzzeichen — Bindestrich, Punkt, Unterstrich und Tilde. Diese müssen nirgends in einer URL kodiert werden; sie trotzdem zu kodieren ist zulässig, aber sinnlos, denn %41 und A bezeichnen dasselbe Zeichen, und ein konformer Parser behandelt sie gleich.

Die reservierte Menge zerfällt in zwei Teile. Die gen-delims trennen die Hauptkomponenten: Doppelpunkt, Schrägstrich, Fragezeichen, Rautenzeichen, öffnende und schließende eckige Klammer sowie das At-Zeichen. Die sub-delims strukturieren das Innere einer Komponente: Ausrufezeichen, Dollar, Kaufmanns-Und, Apostroph, öffnende und schließende runde Klammer, Sternchen, Plus, Komma, Semikolon und Gleichheitszeichen. Alles, was weder unreserviert noch reserviert ist — Steuerzeichen, Leerzeichen, gerades Anführungszeichen, spitze Klammern, Backslash, Zirkumflex, Backtick, geschweifte Klammern, senkrechter Strich und jedes Byte über 127 — muss stets prozentkodiert werden.

Ein Detail erwischt viele. encodeURIComponent lässt Ausrufezeichen, Apostroph, runde Klammern und Sternchen unangetastet, und alle vier sind nach RFC 3986 sub-delims. Diese Zeichen sind dort, wo die Funktion normalerweise eingesetzt wird, zulässig, im Alltag ist das also harmlos; erzeugst du aber einen Wert für ein System, das RFC 3986 streng befolgt — manche Signaturverfahren und OAuth-artige Kanonisierungen tun das —, musst du sie anschließend selbst maskieren. Beachte auch, dass eckige Klammern von beiden JavaScript-Kodierern stets maskiert werden, zu %5B und %5D, weil sie erst nach der Spezifikation dieser Funktionen für IPv6-Literale in die reservierte Menge aufgenommen wurden.

Drei JavaScript-Funktionen auf einer Zeichenkette, und die Plus-Ausnahme

Nimm a b/c?d=café+e&f#g~h*i(j) und lass alle drei laufen. encodeURI liefert a%20b/c?d=caf%C3%A9+e&f#g~h*i(j): Leerzeichen und Akzentbuchstabe werden kodiert, alles Strukturelle bleibt stehen. encodeURIComponent liefert a%20b%2Fc%3Fd%3Dcaf%C3%A9%2Be%26f%23g~h*i(j): Schrägstrich, Fragezeichen, Gleichheitszeichen, Plus, Kaufmanns-Und und Raute werden alle maskiert, denn in der Welt dieser Funktion ist die ganze Zeichenkette ein einziger Wert. escape liefert a%20b/c%3Fd%3Dcaf%E9+e%26f%23g%7Eh*i%28j%29 und damit etwas von beiden Verschiedenes.

Zähle den ASCII-Bereich durch, und der Unterschied wird präzise. Die beiden modernen Funktionen unterscheiden sich in genau elf Zeichen: # $ & + , / : ; = ? @ lässt encodeURI stehen und encodeURIComponent maskiert sie. Diese Liste ist die reservierte Menge, und sie sagt dir, wofür die beiden Funktionen da sind. encodeURI nimmt an, die Zeichenkette sei bereits eine vollständige URL, deren Trennzeichen überleben müssen; encodeURIComponent nimmt an, sie sei ein einzelner Wert, dem kein Trennzeichen einzuführen erlaubt sein darf.

escape ist ein anderes Tier und sollte nie verwendet werden. Es stammt aus der Zeit vor den modernen Spezifikationen und kodiert nach Latin-1 statt UTF-8: é wird %E9 statt des korrekten %C3%A9, und alles oberhalb von U+00FF wird zu einer nichtstandardisierten %uXXXX-Sequenz, das Eurozeichen kommt also als %u20AC heraus. Außerdem lässt es Plus, At-Zeichen und Schrägstrich unmaskiert — allesamt gefährlich in einem Query-Wert — und maskiert dafür unnötig Tilde und runde Klammern. Es überlebt in der Sprache nur aus Abwärtskompatibilität, im Anhang für Funktionen, die es gibt, auf die man sich aber nicht verlassen sollte.

Prozentkodierung nach RFC 3986 kennt genau eine Darstellung für ein Leerzeichen: %20. Sie funktioniert überall — Pfad, Query, Fragment. Das Pluszeichen als Leerzeichen gehört zu einem anderen, älteren Mechanismus: der Serialisierung application/x-www-form-urlencoded für HTML-Formulare, in der Leerzeichen zu Pluszeichen werden und ein wörtliches Plus zu %2B werden muss. Browser nutzen diese Form für den Querystring einer GET-Formularübermittlung — daher siehst du in freier Wildbahn beide Konventionen in Querystrings.

Die Folge ist ein Dekodierfehler, der leicht zu schreiben und schwer zu sehen ist. decodeURIComponent("a+b") liefert a+b mit unverändertem Plus, denn decodeURIComponent setzt RFC 3986 um und weiß nichts von Formularkodierung. Gib dieselbe Zeichenkette einem formularbewussten Parser, und du bekommst a b. Der richtige Dekoder hängt also davon ab, wie die Zeichenkette entstanden ist. In der Praxis ist der verlässliche Zug, auf beiden Seiten aufzuhören zu basteln: Baue Querystrings mit URLSearchParams, das ein Leerzeichen als + serialisiert und ein wörtliches Plus als %2B maskiert, und lies sie mit URLSearchParams zurück, das genau dieselben Regeln umkehrt.

Nicht-ASCII geht zuerst durch UTF-8

Prozentkodierung arbeitet auf Bytes, nicht auf Zeichen; ein Nicht-ASCII-Zeichen muss also erst in Bytes verwandelt werden, bevor es maskiert werden kann. Die moderne Regel lautet UTF-8, danach eine Prozentmaskierung pro Byte. é ist ein einzelnes Zeichen, kodiert als die zwei Bytes c3 a9, wird also %C3%A9. Das Eurozeichen sind drei Bytes, e2 82 ac, wird also %E2%82%AC — neun Zeichen für ein Symbol. Ein Emoji wie U+1F600 sind vier Bytes und wird %F0%9F%98%80, zwölf Zeichen.

Genau hier verrät dich escape, denn es bildet dasselbe é auf das einzelne Byte %E9 ab, seinen Latin-1-Codepunkt. Ein Server, der als UTF-8 dekodiert, sieht eine ungültige Bytefolge und wirft entweder einen Fehler oder erzeugt ein Ersatzzeichen — und der Fehler zeigt sich nur in den Zeilen deiner Daten mit Akzenten. RFC 3986 schreibt selbst keine Zeichenkodierung vor — sie ist älter als die universelle Durchsetzung von UTF-8 und empfiehlt es lediglich für neue Schemata — aber der WHATWG-URL-Standard, den Browser tatsächlich umsetzen, legt durchgehend UTF-8 fest. Behandle UTF-8 als die einzig richtige Antwort.

Doppelkodierung, und wie %2520 entsteht

Das Prozentzeichen ist selbst ein reserviertes Zeichen; eine bereits kodierte Zeichenkette erneut zu kodieren maskiert also die Maskierungen. Beginne mit a b. Einmal kodieren: a%20b. Das kodieren: a%2520b, denn das Prozent wurde zu %25. Nochmals: a%252520b. Jede Runde fügt drei Zeichen und einen weiteren nötigen Dekodierdurchgang hinzu, und die Zeichenkette wächst, ohne je einen Fehler zu werfen.

In echten Systemen passiert das, wenn ein Wert mehrere Schichten durchquert, von denen jede hilfsbereit kodiert, was sie bekommen hat: Ein Client kodiert, ein Gateway kodiert erneut, ein Framework kodiert auf dem Weg in ein Template. Das Symptom ist ein wörtliches %20, das auf einer Seite oder in einem Dateinamen dort erscheint, wo ein Leerzeichen stehen sollte, oder ein 404 auf einem Pfad, der richtig aussieht. Die Heilung ist Disziplin, kein Trick: Bestimme genau eine Stelle in der Pipeline, die die Kodierung besitzt, kodiere dort und reiche überall sonst Rohwerte weiter. Musst du defensiv dekodieren, dekodiere einmal und prüfe, ob das Ergebnis noch ein Prozentzeichen mit zwei Hexziffern enthält, bevor du erneut dekodierst — und sei dir bewusst, dass blindes wiederholtes Dekodieren selbst ein Sicherheitsproblem ist, weil es %252e%252e in .. verwandeln und einen Pfaddurchlauf wieder öffnen kann, den ein einzelner Dekodierschritt geschlossen hatte.

Der Host ist ein anderer Mechanismus: IDN und Punycode

Prozentkodierung gilt nicht für den Domainnamen. DNS-Labels sind auf Buchstaben, Ziffern und Bindestriche beschränkt, internationalisierte Domains nutzen daher eine völlig eigene Transformation: Punycode, definiert in RFC 3492 und eingefasst von den IDNA-Spezifikationen. münchen.de wird xn--mnchen-3ya.de, bücher.example wird xn--bcher-kva.example, und eine japanische Domain wie die beiden Zeichen für Japan gefolgt von .jp wird xn--wgv71a.jp. Das Präfix xn-- kennzeichnet das Label als kodiert; danach folgen die ASCII-Zeichen in Reihenfolge, ein Trenner und dann Anweisungen zum Wiedereinfügen der Nicht-ASCII-Zeichen.

Man kann beide Mechanismen nebeneinander arbeiten sehen. Parse https://münchen.de/straße?q=über alles mit einem Standard-URL-Parser, und heraus kommt https://xn--mnchen-3ya.de/stra%C3%9Fe?q=%C3%BCber%20alles: Der Host ging durch Punycode, Pfad und Query durch UTF-8-Prozentkodierung, und keiner betrat das Gebiet des anderen. Diese Trennung ist nicht kosmetisch. Sie ist der Grund, warum eine Prozentfolge in einem Hostnamen nicht so dekodiert wird, wie man erwarten könnte, und warum Homograph-Angriffe — eine Domain registrieren, deren Unicode-Zeichen denen einer anderen ähneln — ein Problem der Punycode-Schicht sind, dem Browser mit Anzeigeregeln statt mit Kodierung begegnen.

Vier Regeln, die den meisten Ärger verhindern

Erstens: Baue eine URL nie durch Zeichenkettenverkettung, wenn ein URL-Builder verfügbar ist. new URL() und URLSearchParams wissen, in welcher Komponente sie sich befinden, und kodieren entsprechend — genau dieses Wissen fehlt einem Template-Literal. Zweitens: Kodiere Werte, nicht URLs. Wende encodeURIComponent auf jedes einzelne Pfadsegment und jeden einzelnen Query-Wert an und reserviere encodeURI für eine fertige URL, die du selbst gebaut hast. Drittens: Kodiere genau einmal, in einer einzigen zuständigen Schicht, und reiche überall sonst Rohwerte weiter — allein das beseitigt die gesamte Klasse der %2520-Fehler. Viertens: Lösche escape aus deiner Codebasis; es kodiert Latin-1 und lässt gefährliche Zeichen stehen, und es gibt keine Lage, in der es die richtige Antwort ist.

Häufige Fragen

Was ist der Unterschied zwischen encodeURI und encodeURIComponent?

Genau elf Zeichen. encodeURI lässt # $ & + , / : ; = ? @ stehen; encodeURIComponent maskiert sie alle. Diese Liste ist die reservierte Menge aus RFC 3986, und sie sagt dir, wovon jede Funktion ausgeht. encodeURI glaubt, du hättest ihm eine vollständige URL gegeben, deren Trennzeichen weiter funktionieren müssen, und maskiert daher nur, was nie Struktur sein könnte — Leerzeichen, Nicht-ASCII, Steuerzeichen. encodeURIComponent glaubt, du hättest ihm einen einzelnen Wert gegeben, der kein Trennzeichen einführen darf, und maskiert daher alles Reservierte. Auf der Zeichenkette a b/c?d=café+e&f#g~h*i(j) liefert das erste a%20b/c?d=caf%C3%A9+e&f#g~h*i(j) und das zweite a%20b%2Fc%3Fd%3Dcaf%C3%A9%2Be%26f%23g~h*i(j). Nimm encodeURIComponent für jedes Pfadsegment und jeden Query-Wert — das ist fast immer, was du willst. Nimm encodeURI nur für eine ganze URL, die du selbst gebaut hast und der du bereits traust; es auf Nutzereingaben anzuwenden macht diese Eingabe nicht sicher, denn es bewahrt absichtlich genau die Zeichen, die ein eingeschleuster Wert bräuchte.

Sollte ein Leerzeichen %20 oder ein Pluszeichen sein?

%20 ist immer richtig; ein Pluszeichen nur in einem bestimmten Kontext. Die Prozentkodierung nach RFC 3986 kennt genau eine Darstellung für ein Leerzeichen, %20, und sie ist in Pfad, Query und Fragment gleichermaßen gültig. Das Plus als Leerzeichen stammt aus application/x-www-form-urlencoded, der älteren Serialisierung von HTML-Formularen, in der Leerzeichen zu Plus werden und ein wörtliches Plus %2B geschrieben werden muss. Browser wenden das beim Absenden eines GET-Formulars an, deshalb enthalten echte Querystrings beide Konventionen. Die praktische Gefahr liegt beim Dekodieren: decodeURIComponent("a+b") liefert a+b mit unverändertem Plus, denn es setzt RFC 3986 um und weiß nichts von Formularen, während ein formularbewusster Parser a b liefert. Entscheide nicht von Fall zu Fall. Baue Querystrings mit URLSearchParams und lies sie mit URLSearchParams zurück, damit in beide Richtungen dieselben Regeln gelten. In einem Pfadsegment nimm stets %20 — ein Plus ist dort ein wörtliches Pluszeichen und sonst nichts.

Warum sehe ich %2520 in meinen URLs?

Weil etwas eine bereits kodierte Zeichenkette erneut kodiert hat. Das Prozentzeichen ist selbst reserviert und wird beim Maskieren zu %25. Nimm a b, kodiere zu a%20b, dann kodiere dieses Ergebnis: Das Prozent wird zu %25, und du bekommst a%2520b. Noch einmal, und du bekommst a%252520b. Nichts bricht ab, die Zeichenkette wächst nur um drei Zeichen pro Runde und braucht einen zusätzlichen Dekodierdurchgang. In echten Systemen passiert das, wenn mehrere Schichten höflich je das kodieren, was sie erhalten haben — ein Client, dann ein Gateway, dann ein Framework beim Rendern in ein Template. Das Symptom ist ein wörtliches %20 dort, wo ein Leerzeichen stehen sollte, oder ein 404 auf einem Pfad, der richtig aussieht. Die Lösung ist architektonisch: Bestimme genau eine Schicht, die die Kodierung besitzt, kodiere dort und transportiere überall sonst Rohwerte. Vermeide es, in einer Schleife zu dekodieren, bis kein Prozent mehr übrig ist — das ist eine eigene Schwachstelle: Wiederholtes Dekodieren kann %252e%252e in .. verwandeln und einen Pfaddurchlauf wieder öffnen, den ein einzelner Dekodierschritt eingedämmt hatte.

Muss ich nicht-englische Zeichen in einer URL kodieren?

Ja, und die Kodierung läuft zuerst durch UTF-8. Prozentkodierung arbeitet auf Bytes, ein Zeichen muss also erst zu Bytes werden, bevor es maskiert werden kann, und die moderne Regel lautet: als UTF-8 kodieren, dann eine Prozentmaskierung pro Byte schreiben. é sind zwei Bytes, c3 a9, und wird %C3%A9. Das Eurozeichen sind drei Bytes und wird %E2%82%AC, neun Zeichen für ein Symbol. Ein Emoji bei U+1F600 sind vier Bytes und wird %F0%9F%98%80. Das zählt für Speichergrößen und für jede Längenbegrenzung, die du durchsetzt, denn ein Zeichen kann zwölf kosten. Es erklärt auch, warum die veraltete Funktion escape Daten beschädigt: Sie gibt Latin-1 aus und macht aus é das einzelne Byte %E9, das ein UTF-8-Dekoder als ungültig zurückweist — und der Schaden zeigt sich nur in deinen Datensätzen mit Akzenten. Der Host ist die Ausnahme: Domainnamen werden gar nicht prozentkodiert, sondern mit Punycode umgewandelt, münchen.de wird also xn--mnchen-3ya.de, während Pfad und Query daneben gewöhnliche UTF-8-Prozentkodierung nutzen.

Reicht Prozentkodierung, um Nutzereingaben sicher zu machen?

Nein, denn Kodierung ist kontextabhängig, und eine URL ist nur einer der Kontexte, die ein Wert durchläuft. encodeURIComponent hindert einen Wert daran, aus seiner URL-Komponente auszubrechen: Ein Schrägstrich wird %2F und kann kein neues Pfadsegment beginnen, ein Kaufmanns-Und wird %26 und kann keinen neuen Parameter beginnen. Das ist echt und wichtig. Für den nächsten Schritt tut es nichts. Derselbe Wert in HTML braucht HTML-Maskierung, in einer SQL-Anweisung eine parametrisierte Abfrage, in einem Shell-Befehl argumentweises Quoting, in einem JavaScript-Zeichenkettenliteral eine eigene Maskierung. Für den falschen Kontext zu kodieren ist kein Teilschutz, sondern gar kein Schutz. Zwei weitere Warnungen: encodeURI ist kein Eingabefilter, da es die reservierten Zeichen, die ein Angreifer bräuchte, absichtlich bewahrt — wende es nie als Sicherheitsmaßnahme auf unvertraute Daten an; und wiederholtes Dekodieren, bis kein Prozentzeichen mehr übrig ist, kann Folgen rekonstruieren, die ein einzelner Dekodierschritt entschärft hatte, insbesondere %252e%252e wieder in einen Pfaddurchlauf verwandeln.

Wie passen internationalisierte Domainnamen dazu?

Sie nutzen überhaupt keine Prozentkodierung. DNS-Labels sind auf Buchstaben, Ziffern und Bindestriche beschränkt, eine Domain mit anderem Inhalt wird daher mit Punycode umgewandelt, definiert in RFC 3492 und geregelt durch die IDNA-Spezifikationen. münchen.de wird xn--mnchen-3ya.de, bücher.example wird xn--bcher-kva.example, und eine japanische Domain wie die beiden Zeichen für Japan gefolgt von .jp wird xn--wgv71a.jp. Das Präfix xn-- markiert das Label als kodiert, der Rest enthält die ASCII-Zeichen samt Anweisungen, die übrigen wieder einzusetzen. Beide Systeme siehst du zugleich, wenn du eine URL wie https://münchen.de/straße?q=über alles parst: Das Ergebnis ist https://xn--mnchen-3ya.de/stra%C3%9Fe?q=%C3%BCber%20alles, Punycode am Host und UTF-8-Prozentkodierung in allem danach. Praktisch heißt das: Prozentkodiere nie einen Hostnamen und vergleiche Hostnamen in ihrer Punycode-Form. Es ist auch der Grund, warum Homograph-Angriffe über die Anzeigepolitik des Browsers behandelt werden und nicht über Kodierung — die beiden Namen sind wirklich verschiedene Labels, die nur ähnlich aussehen.