new URL() — Methode · JavaScript-Referenz

Signatur

new URL(url, base)

Beschreibung

Der Konstruktor new URL() parst eine Zeichenkette nach dem WHATWG URL Standard und liefert ein URL-Objekt, dessen Bestandteile wie protocol, host, pathname, search oder hash einzeln gelesen und verändert werden können. So musst du URLs nicht fehleranfällig per String-Verkettung oder regulären Ausdrücken zusammenbauen.

Gibst du einen zweiten Parameter base an, wird url relativ zu dieser Basis aufgelöst – genau so, wie ein Browser einen relativen Link in einem Dokument auflöst. Ist url bereits absolut, wird base ignoriert.

Typische Einsatzfälle sind das sichere Zusammensetzen von API-Endpunkten, das Auslesen und Ändern von Query-Parametern über url.searchParams, das Prüfen, ob ein Link auf die eigene Domain zeigt, sowie die Normalisierung von Benutzereingaben.

Kann die Eingabe nicht als gültige URL geparst werden, wirft der Konstruktor einen TypeError. Deshalb gehört er bei unzuverlässigen Eingaben in einen try...catch-Block, oder du prüfst vorher mit URL.canParse().

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string \| URL		Absolute oder relative URL. Objekte mit `toString()`-Methode (z. B. ein anderes `URL`-Objekt oder `HTMLAnchorElement`) werden in einen String umgewandelt.
$base	string \| URL	undefined	Basis-URL, gegen die eine relative `url` aufgelöst wird. Muss selbst eine gültige absolute URL sein, sonst wird ein `TypeError` geworfen.

Rückgabewert

Typ

URL

Beschreibung

Ein neues URL-Objekt mit den geparsten und normalisierten Bestandteilen der URL.

Beispiele

URL zerlegen und Bestandteile auslesen

const url = new URL('https://user:pw@shop.example.com:8080/produkte/liste?kategorie=buch&seite=2#top');

console.log(url.protocol);  // Schema
console.log(url.hostname);
console.log(url.port);
console.log(url.pathname);
console.log(url.searchParams.get('seite'));
console.log(url.hash);
console.log(url.origin);

https: shop.example.com 8080 /produkte/liste 2 #top https://shop.example.com:8080

Relative Pfade gegen eine Basis-URL auflösen

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

console.log(new URL('users/42', base).href);
console.log(new URL('../v2/users', base).href);
console.log(new URL('/status', base).href);
// Absolute URL: base wird ignoriert
console.log(new URL('https://cdn.example.org/a.js', base).href);

https://api.example.com/v1/users/42 https://api.example.com/v2/users https://api.example.com/status https://cdn.example.org/a.js

API-Anfrage mit Query-Parametern sicher aufbauen

const buildSearchUrl = (term, page = 1) => {
  const url = new URL('/search', 'https://api.example.com');
  url.searchParams.set('q', term);       // wird automatisch kodiert
  url.searchParams.set('page', String(page));
  return url;
};

const url = buildSearchUrl('Kaffee & Kuchen', 3);
console.log(url.toString());

// const response = await fetch(url);

https://api.example.com/search?q=Kaffee+%26+Kuchen&page=3

Benutzereingabe validieren und externe Links erkennen

const parseUserUrl = (input) => {
  try {
    const url = new URL(input);
    if (!['http:', 'https:'].includes(url.protocol)) return null;
    return url;
  } catch {
    return null; // TypeError: ungültige URL
  }
};

console.log(parseUserUrl('example.com'));
console.log(parseUserUrl('javascript:alert(1)'));

const link = parseUserUrl('https://extern.example.net/seite');
const isExternal = link && link.origin !== 'https://www.meine-seite.de';
console.log(isExternal);

null null true

// Wichtig · Fallstricke

Ungültige Eingaben werfen einen Fehler: Bei einer unparsbaren URL (z. B. new URL('example.com') ohne Schema und ohne Basis) wirft der Konstruktor einen TypeError. Deshalb try...catch verwenden oder vorher mit URL.canParse(url, base) prüfen (Baseline seit 2023, Node.js 19.9+). URL.parse() (sehr neu) gibt statt eines Fehlers null zurück.
Schrägstrich am Ende der Basis: new URL('users', 'https://api.example.com/v1') ergibt /users, nicht /v1/users, weil das letzte Pfadsegment ohne abschließenden / ersetzt wird. Ein führender / in url ersetzt den gesamten Pfad der Basis.
Sicherheit: Ein gültiges URL-Objekt ist nicht automatisch ungefährlich. Bevor du Benutzer-URLs in href, src oder Weiterleitungen einsetzt, prüfe protocol (z. B. javascript: oder data: ablehnen) und gegebenenfalls origin gegen eine Whitelist, um XSS und offene Weiterleitungen (Open Redirects) zu vermeiden.
Normalisierung: Hostnamen werden kleingeschrieben und Internationalized Domain Names in Punycode umgewandelt (münchen.de → xn--mnchen-3ya.de). Standardports wie :443 bei https entfallen, Sonderzeichen im Pfad werden prozentkodiert.
Kompatibilität: In allen modernen Browsern und in Web Workern verfügbar. Der Internet Explorer unterstützt den Konstruktor nicht. In Node.js ist URL ab Version 10 global verfügbar. Das veraltete url.parse() aus Node.js folgt nicht dem WHATWG-Standard und sollte nicht mehr verwendet werden.

Siehe auch

URL URL.searchParams URL.parse() URLSearchParams encodeURIComponent()