URL.parse() — Methode · JavaScript-Referenz

Signatur

URL.parse(url, base)

Beschreibung

URL.parse() ist eine statische Methode des URL-Interfaces. Sie wertet eine absolute oder relative URL aus, relative URLs optional gegen eine Basis-URL, und gibt ein neues URL-Objekt zurück. Die Methode arbeitet wie der Konstruktor new URL(url, base), mit einem Unterschied: Ist die URL ungültig, wird keine TypeError geworfen, sondern es kommt einfach null zurück.

Das ist praktisch, wenn Eingaben aus unsicheren Quellen kommen, etwa aus Formularfeldern, Query-Parametern, Konfigurationsdateien oder API-Antworten. Um den Aufruf herum braucht es dann keinen try...catch-Block. Auswerten und Prüfen passieren in einem Schritt, und mit optionaler Verkettung (?.) oder dem Nullish-Coalescing-Operator (??) lässt sich der Code sehr kompakt schreiben.

Wenn Sie nur wissen wollen, ob eine URL gültig ist, reicht URL.canParse(). Brauchen Sie danach aber ihre Bestandteile wie hostname, pathname oder searchParams, ist URL.parse() besser: Die URL wird dann nur einmal ausgewertet.

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL \| { toString(): string }		Absolute oder relative URL. Objekte werden über `toString()` in eine Zeichenkette umgewandelt. Ist `url` relativ, muss `base` angegeben werden.
$base	string \| URL	undefined	Basis-URL, gegen die eine relative `url` aufgelöst wird. Ist `url` absolut, wird `base` ignoriert. Ist `base` selbst ungültig, ist das Ergebnis `null`.

Rückgabewert

Typ

URL | null

Beschreibung

Ein neues URL-Objekt, wenn die Eingabe gültig ist, sonst null.

Beispiele

Grundlegende Nutzung: gültige und ungültige URLs

const ok = URL.parse('https://programmierung.net/js/url?tab=api#parse');
console.log(ok.hostname);
console.log(ok.searchParams.get('tab'));

const kaputt = URL.parse('kein gültiger URL');
console.log(kaputt);

programmierung.net api null

Relative URL gegen eine Basis-URL auflösen

const base = 'https://example.com/docs/api/';

console.log(URL.parse('../guide/start.html', base)?.href);
console.log(URL.parse('/impressum', base)?.href);
// Absolute URL: base wird ignoriert
console.log(URL.parse('https://mdn.dev/', base)?.href);
// Relative URL ohne Basis ist ungültig
console.log(URL.parse('/impressum'));

https://example.com/docs/guide/start.html https://example.com/impressum https://mdn.dev/ null

Benutzereingabe prüfen und nur HTTP(S) erlauben

const parseSafeLink = (input) => {
  const url = URL.parse(input.trim());
  if (!url || !['http:', 'https:'].includes(url.protocol)) {
    return null;
  }
  return url;
};

console.log(parseSafeLink('  https://example.com/profil  ')?.href);
console.log(parseSafeLink('javascript:alert(1)'));
console.log(parseSafeLink('www.example.com'));

https://example.com/profil null null

Fallback mit Feature-Erkennung für ältere Umgebungen

const parseUrl = (url, base) => {
  if (typeof URL.parse === 'function') {
    return URL.parse(url, base);
  }
  try {
    return new URL(url, base);
  } catch {
    return null;
  }
};

const redirect = parseUrl(new URLSearchParams('?next=/konto').get('next'), 'https://example.com');
console.log(redirect?.pathname ?? '/');

/konto

// Wichtig · Fallstricke

Browser-Kompatibilität: URL.parse() ist relativ neu (Chrome/Edge 126, Firefox 126, Safari 18, Node.js 22.1). Für ältere Browser brauchen Sie einen Fallback mit try { new URL(...) } catch {} oder ein Polyfill wie core-js.
Gültig heißt nicht sicher: Auch javascript:alert(1) oder data:-URLs sind syntaktisch gültig. Bevor Sie Benutzereingaben in href, src oder Weiterleitungen einsetzen, prüfen Sie immer protocol (und bei Bedarf origin). Sonst drohen XSS-Lücken oder offene Weiterleitungen (Open Redirects).
Nachsichtige Auswertung: Nach dem WHATWG-URL-Standard werden Eingaben normalisiert. Leerzeichen am Rand werden entfernt, Hostnamen kleingeschrieben und per Punycode kodiert, Pfade mit .. aufgelöst. 'www.example.com' ohne Schema ist dagegen ungültig.
Ist url relativ und fehlt base, oder ist base selbst ungültig, gibt die Methode null zurück.
Das Ergebnis ist ein neues, veränderbares Objekt. Änderungen daran wirken sich nicht auf ein als base übergebenes URL-Objekt aus.

Siehe auch

URL URL.canParse() URL.searchParams URLSearchParams URL.href new Image()