Was ist der Unterschied zwischen encodeURI und encodeURIComponent?

Was ist encodeURI()?

encodeURI() ist eine in JavaScript integrierte Funktion, die dazu dient, einen vollständigen Uniform Resource Identifier (URI) zu kodieren. Sie wandelt Zeichen, die in einem URI nicht zulässig sind, in ihre Percent-Encoding-Entsprechungen um, behält aber bewusst jene Zeichen bei, die innerhalb eines URI eine strukturelle Bedeutung haben.

Konkret kodiert encodeURI() die folgenden Zeichen nicht: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. Das bedeutet, dass die gesamte Struktur der URL nach dem Kodieren erhalten bleibt.

// encodeURI() behält die URL-Struktur bei
const url = 'https://example.com/my page?name=John Doe&city=New York';
console.log(encodeURI(url));
// "https://example.com/my%20page?name=John%20Doe&city=New%20York"
// Beachte: :, /, ?, & und = werden NICHT kodiert

Dieses Verhalten macht encodeURI() ideal, wenn du eine vollständige URL hast, die Leerzeichen oder Nicht-ASCII-Zeichen enthalten kann, deren strukturelle Zeichen (Protokolltrenner, Pfadtrennzeichen, Query-String-Markierungen) aber unverändert bleiben sollen.

Was ist encodeURIComponent()?

encodeURIComponent() ist dafür konzipiert, eine einzelne Komponente eines URI zu kodieren, etwa den Wert eines Query-Parameters oder ein Pfadsegment. Anders als encodeURI() kodiert es nahezu jedes Sonderzeichen, einschließlich derjenigen, die in URLs eine strukturelle Bedeutung haben.

Die einzigen Zeichen, die encodeURIComponent() nicht kodiert, sind: A-Z a-z 0-9 - _ . ! ~ * ' ( ). Alles andere, einschließlich /, ?, &, =, # und :, wird mittels Percent-Encoding umgewandelt.

// encodeURIComponent() kodiert alles außer den unreservierten Zeichen
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Beachte: &, / und ? WERDEN kodiert

// Aufbau einer URL mit einem Query-Parameter
const url = 'https://example.com/search?q=' + encodeURIComponent(value);
// "https://example.com/search?q=Tom%20%26%20Jerry%20%2F%20Friends%3F"

Da es strukturelle Zeichen kodiert, solltest du encodeURIComponent() niemals auf eine vollständige URL anwenden. Andernfalls würden das ://, alle /-Pfadtrenner und das ?-Query-Trennzeichen kodiert, wodurch die URL unbrauchbar würde.

Die wichtigsten Unterschiede auf einen Blick

Merkmal	encodeURI()	encodeURIComponent()
Zweck	Kodiert einen vollständigen URI	Kodiert eine URI-Komponente
Kodiert /	Nein	Ja (%2F)
Kodiert ?	Nein	Ja (%3F)
Kodiert &	Nein	Ja (%26)
Kodiert =	Nein	Ja (%3D)
Kodiert #	Nein	Ja (%23)
Kodiert :	Nein	Ja (%3A)
Kodiert Leerzeichen	Ja (%20)	Ja (%20)
Kodiert Unicode	Ja	Ja

Wann welche Funktion zu verwenden ist

Die Regel ist unkompliziert: Verwende encodeURI(), wenn du eine vollständige URL kodieren und dabei ihre Struktur gültig halten möchtest. Verwende encodeURIComponent(), wenn du einen einzelnen Wert kodieren möchtest, der in eine URL eingefügt wird.

// Szenario 1: Kodieren einer vollständigen URL mit Leerzeichen
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Szenario 2: Aufbau einer URL aus einzelnen Teilen
const baseUrl = 'https://api.example.com/search';
const query = 'price >= 100 & category = books';
const finalUrl = baseUrl + '?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// Szenario 3: Kodieren einer Redirect-URL als Parameter
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// Die gesamte Redirect-URL wird als einzelner Parameterwert kodiert

Häufige Fehler und wie man sie vermeidet

Fehler 1: encodeURI() für Werte von Query-Parametern verwenden. Da encodeURI() weder & noch = kodiert, wird die Struktur des Query-Strings beschädigt, wenn man es auf einen Parameterwert anwendet, der diese Zeichen enthält.

// FALSCH
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// Der Server sieht q="salt " und einen zusätzlichen Parameter " pepper"

// RICHTIG
const good = 'https://example.com/search?q=' + encodeURIComponent('salt & pepper');
// "https://example.com/search?q=salt%20%26%20pepper"

Fehler 2: encodeURIComponent() auf eine vollständige URL anwenden. Dadurch wird die URL-Struktur zerstört, weil alle Schrägstriche, Doppelpunkte und Fragezeichen kodiert werden.

// FALSCH
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// Das ist keine gültige URL mehr!

// RICHTIG
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (bereits gültig, es gibt nichts zu kodieren)

Fehler 3: Doppelte Kodierung. Wenn eine Zeichenkette bereits Percent-encodiert ist, werden bei einer erneuten Kodierung die %-Zeichen kodiert, sodass aus %20 ein %2520 wird. Prüfe immer, ob ein Wert bereits kodiert wurde, bevor du Kodierungsfunktionen anwendest.

Eine sicherere, moderne Alternative sind die URL- und URLSearchParams-APIs, die die Kodierung automatisch übernehmen und dir helfen, diese Fallstricke vollständig zu vermeiden.