URLs in JavaScript decodieren (Vollständiger Leitfaden)

decodeURIComponent() — Eine URI-Komponente decodieren

decodeURIComponent() ist die wichtigste Funktion zum Decodieren URL-codierter Zeichenketten in JavaScript. Sie decodiert alle prozentcodierten Sequenzen und wandelt sie zurück in ihre ursprünglichen Zeichen um. Verwenden Sie diese Funktion, wenn Sie Werte von Query-Parametern, Pfadsegmente oder eine beliebige einzelne Komponente einer URI decodieren möchten.

// Einfaches Decodieren
console.log(decodeURIComponent('hello%20world'));
// "hello world"

console.log(decodeURIComponent('price%3D10%26qty%3D2'));
// "price=10&qty=2"

// Unicode-Zeichen decodieren
console.log(decodeURIComponent('caf%C3%A9'));
// "cafe" (mit Akzent)

console.log(decodeURIComponent('%E4%B8%AD%E6%96%87'));
// Chinesische Zeichen

// Wert eines Query-Parameters aus einer URL decodieren
const url = 'https://example.com/search?q=C%2B%2B%20%26%20Java';
const params = url.split('?')[1];
const value = params.split('=')[1];
console.log(decodeURIComponent(value));
// "C++ & Java"

decodeURIComponent() decodiert alle prozentcodierten Sequenzen, einschließlich derjenigen für reservierte Zeichen wie %2F (/) und %3F (?). Das ist beim Arbeiten mit einzelnen URI-Komponenten das korrekte Verhalten, kann jedoch zu Problemen führen, wenn es auf eine vollständige URL angewendet wird.

decodeURI() — Eine vollständige URI decodieren

decodeURI() decodiert eine vollständige URI und bewahrt dabei ihre Struktur. Anders als decodeURIComponent() decodiert es keine Sequenzen, die reservierte URI-Zeichen darstellen, etwa %2F (/), %3F (?), %23 (#) und %26 (&).

// decodeURI bewahrt die URI-Struktur
console.log(decodeURI('https://example.com/my%20page?q=hello%20world'));
// "https://example.com/my page?q=hello world"
// Leerzeichen werden decodiert, aber /, ? und = bleiben erhalten

// Vergleich mit decodeURIComponent bei einer vollständigen URL
console.log(decodeURIComponent('https%3A%2F%2Fexample.com%2Fpath'));
// "https://example.com/path" - decodiert korrekt, wenn die gesamte URL codiert war

// decodeURI decodiert keine Sequenzen reservierter Zeichen
console.log(decodeURI('path%2Fto%2Ffile'));
// "path%2Fto%2Ffile" - %2F wird NICHT decodiert, da / reserviert ist
console.log(decodeURIComponent('path%2Fto%2Ffile'));
// "path/to/file" - %2F WIRD decodiert

Verwenden Sie decodeURI(), wenn Sie eine URL lesbarer machen möchten (zum Beispiel für die Anzeige), ohne ihre Struktur zu verändern. Für die meisten programmatischen Anwendungsfälle werden Sie decodeURIComponent() auf einzelne Komponenten anwenden wollen.

Umgang mit fehlerhaften URIs

Sowohl decodeURI() als auch decodeURIComponent() werfen einen URIError, wenn sie auf ungültige prozentcodierte Sequenzen stoßen. Das geschieht bei einzelnen Prozentzeichen, unvollständigen Sequenzen oder ungültigen UTF-8-Bytefolgen. Umschließen Sie Decodiervorgänge immer mit einem try-catch-Block, wenn Sie mit von Benutzern bereitgestellten oder externen URLs arbeiten.

// Diese werfen URIError: URI malformed
try {
  decodeURIComponent('%');         // einzelnes Prozentzeichen
} catch (e) {
  console.error(e.message);       // "URI malformed"
}

try {
  decodeURIComponent('%2');        // unvollständige Sequenz
} catch (e) {
  console.error(e.message);       // "URI malformed"
}

// Sichere Decodierfunktion
function safeDecode(str) {
  try {
    return decodeURIComponent(str);
  } catch (e) {
    console.warn('Failed to decode:', str);
    return str; // bei Fehler die ursprüngliche Zeichenkette zurückgeben
  }
}

// Fehlerhafte Prozentsequenzen vor dem Decodieren korrigieren
function fixAndDecode(str) {
  // Einzelnes % durch %25 (codiertes Prozentzeichen) ersetzen
  const fixed = str.replace(/%(?![0-9A-Fa-f]{2})/g, '%25');
  return decodeURIComponent(fixed);
}

console.log(fixAndDecode('100% complete'));
// "100% complete"

Die URL-API verwenden (Empfohlen)

Die modernen APIs URL und URLSearchParams bieten eine sicherere und stärker strukturierte Möglichkeit, URLs zu parsen und zu decodieren. Sie übernehmen das Codieren und Decodieren automatisch und verringern so das Fehlerrisiko.

// Eine URL parsen und auf ihre Komponenten zugreifen (automatisch decodiert)
const url = new URL('https://example.com/path%20here?q=hello%20world&lang=en');

console.log(url.pathname);  // "/path here" (decodiert)
console.log(url.search);    // "?q=hello%20world&lang=en" (roh)

// URLSearchParams decodiert Parameterwerte automatisch
console.log(url.searchParams.get('q'));     // "hello world"
console.log(url.searchParams.get('lang')); // "en"

// Über alle Parameter iterieren
for (const [key, value] of url.searchParams) {
  console.log(key, '=', value);
}
// q = hello world
// lang = en

// URLSearchParams behandelt + als Leerzeichen (Formularcodierung)
const formParams = new URLSearchParams('q=hello+world&lang=en');
console.log(formParams.get('q'));  // "hello world"

// URLs mit automatischer Codierung erstellen
const newUrl = new URL('https://example.com/search');
newUrl.searchParams.set('q', 'C++ & Java');
newUrl.searchParams.set('page', '1');
console.log(newUrl.toString());
// "https://example.com/search?q=C%2B%2B+%26+Java&page=1"

Häufige Fehler beim Decodieren

Fehler 1: Eine vollständige URL mit decodeURIComponent() decodieren. Das kann die URL-Struktur zerstören, wenn sie codierte reservierte Zeichen enthält. Ein %2F in einem Query-Wert würde zu einem / und könnte so die Bedeutung der URL verändern.

Fehler 2: Doppeltes Decodieren. Wurde eine Zeichenkette bereits einmal decodiert, kann ein erneutes Decodieren zu unerwarteten Ergebnissen oder Fehlern führen. Zum Beispiel decodiert die Zeichenkette %2520 zunächst zu %20 und anschließend zu einem Leerzeichen. Wenn Sie nur eine Codierungsebene erwarten, beschädigt doppeltes Decodieren die Daten.

// Problem des doppelten Decodierens
const encoded = '%2520'; // Dies ist ein codiertes %20
console.log(decodeURIComponent(encoded));  // "%20" (korrekt - eine Ebene)
console.log(decodeURIComponent(decodeURIComponent(encoded)));  // " " (doppelt decodiert!)

// Vor dem Decodieren prüfen, ob eine Zeichenkette decodiert werden muss
function needsDecoding(str) {
  return str !== decodeURIComponent(str);
}

Fehler 3: Das Pluszeichen nicht berücksichtigen. decodeURIComponent() wandelt + nicht in Leerzeichen um. Wenn Sie form-urlencodierte Daten decodieren, müssen Sie + zuerst durch Leerzeichen ersetzen oder URLSearchParams verwenden, das dies automatisch übernimmt.

// decodeURIComponent decodiert + NICHT als Leerzeichen
console.log(decodeURIComponent('hello+world'));
// "hello+world" (nicht "hello world"!)

// Lösung: + vor dem Decodieren ersetzen
function decodeFormValue(str) {
  return decodeURIComponent(str.replace(/\+/g, ' '));
}
console.log(decodeFormValue('hello+world'));
// "hello world"

// Oder URLSearchParams verwenden (behandelt + automatisch)
const params = new URLSearchParams('q=hello+world');
console.log(params.get('q'));
// "hello world"