encodeURIComponent vs. encodeURI: Wann welche Funktion verwenden

Die zwei JavaScript-Funktionen zur URL-Kodierung

JavaScript stellt zwei integrierte Funktionen zur URL-Kodierung bereit: encodeURI() und encodeURIComponent(). Auf den ersten Blick wirken sie ähnlich, doch die falsche Wahl kann zu kaputten URLs, Sicherheitslücken oder Datenkorruption führen. Den Unterschied zu verstehen ist für Webentwickler entscheidend.

encodeURI() – Für vollständige URIs

encodeURI() ist dafür gedacht, eine vollständige URI zu kodieren. Die Funktion kodiert alle Zeichen mit Ausnahme derjenigen, die innerhalb der URI-Struktur eine besondere Bedeutung haben. Konkret werden folgende Zeichen NICHT kodiert:

• Reservierte Zeichen: ; , / ? : @ & = + $ #
• Nicht reservierte Zeichen: Buchstaben, Ziffern, - _ . ! ~ * ' ( )

// encodeURI erhält die URI-Struktur
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Hinweis: :, /, ?, =, & werden NICHT kodiert

encodeURIComponent() – Für URI-Komponenten

encodeURIComponent() ist dafür gedacht, eine einzelne Komponente einer URI zu kodieren (zum Beispiel den Wert eines Query-Parameters). Die Funktion kodiert ALLE Zeichen mit Ausnahme von:

• Nicht reservierten Zeichen: Buchstaben, Ziffern, - _ . ! ~ * ' ( )

// encodeURIComponent kodiert alles außer nicht reservierten Zeichen
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Hinweis: & WIRD kodiert, da es ein reserviertes Zeichen ist

// Verwendung für den Wert eines Query-Parameters
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Häufige Fehler

Fehler 1: encodeURI für Query-Werte verwenden

Wenn Sie encodeURI() verwenden, um den Wert eines Query-Parameters zu kodieren, der ein kaufmännisches Und enthält, wird dieses nicht kodiert und als Parametertrenner interpretiert – was Ihre URL zerstört.

// FALSCH: das kaufmännische Und im Wert zerstört die URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// Der Server sieht: q="Tom " und einen Parameter " Jerry" ohne Wert

// RICHTIG: encodeURIComponent verwenden
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// Der Server sieht korrekt: q="Tom & Jerry"

Fehler 2: encodeURIComponent für vollständige URLs verwenden

Wenn Sie encodeURIComponent() auf eine komplette URL anwenden, werden die Doppelpunkte, Schrägstriche, Fragezeichen und andere strukturelle Zeichen kodiert, wodurch die URL vollständig unbrauchbar wird.

Wann welche Funktion: Die einfache Regel

• Verwenden Sie encodeURI(), wenn Sie eine vollständige URI haben, die möglicherweise Leerzeichen oder Nicht-ASCII-Zeichen enthält, deren Struktur aber gültig ist.
• Verwenden Sie encodeURIComponent(), wenn Sie ein einzelnes Datenstück kodieren, das in eine URI eingefügt wird (Werte von Query-Parametern, Pfadsegmente usw.).

Die Alternative: URLSearchParams

Modernes JavaScript stellt die URLSearchParams-API bereit, die die Kodierung automatisch übernimmt. Für das Erstellen von Query-Strings ist dies oft der beste Ansatz:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// Oder die URL-API verwenden
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());