URL.port — Eigenschaft · JavaScript-Referenz

Signatur

URL.port

Beschreibung

Die Eigenschaft port eines URL-Objekts enthält die Portnummer der URL als Zeichenkette, nicht als Zahl. Enthält die URL keinen ausdrücklichen Port, ist der Wert ein Leerstring "".

Wichtig: Der URL-Parser normalisiert Standardports. Steht in der URL der übliche Port des Schemas (z. B. 443 bei https:, 80 bei http: und ws:, 21 bei ftp:), wird er entfernt und port gibt "" zurück. Aus https://example.com:443/ wird also https://example.com/.

Die Eigenschaft ist schreibbar. Beim Zuweisen wird der Wert in eine Zeichenkette umgewandelt und es werden nur die führenden Ziffern übernommen. Ungültige Werte (ohne führende Ziffern oder größer als 65535) werden stillschweigend ignoriert, der alte Port bleibt dann erhalten. Mit einem Leerstring entfernst du den Port. href, host und origin werden automatisch mit angepasst.

Typische Einsatzfälle: Ports von Entwicklungs- und Produktionsservern austauschen, Konfigurations-URLs prüfen oder den tatsächlich verwendeten Port bestimmen. Für Letzteres musst du selbst auf den Standardport des Schemas zurückgreifen, wenn port leer ist.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| number		Nur beim Setzen: der neue Port. Wird in eine Zeichenkette umgewandelt, übernommen werden nur die führenden Ziffern (0–65535). Mit `""` wird der Port entfernt. Der Standardport des Schemas ergibt ebenfalls `""`.

Rückgabewert

Typ

string

Beschreibung

Die Portnummer als Zeichenkette, z. B. "8080". Ein Leerstring "", wenn kein Port angegeben ist oder der Standardport des Schemas verwendet wird.

Beispiele

Port auslesen und Standardport-Normalisierung

const api = new URL('https://example.com:8443/api/v1');
console.log(api.port);

const standard = new URL('https://example.com:443/login');
console.log(standard.port === '');
console.log(standard.href);

const ohnePort = new URL('http://localhost/');
console.log(JSON.stringify(ohnePort.port));

8443 true https://example.com/login ""

Port für den Entwicklungsserver umschreiben

const toDevUrl = (input, devPort = 5173) => {
  const url = new URL(input);
  url.hostname = 'localhost';
  url.protocol = 'http:';
  url.port = devPort; // Zahl wird zu "5173"
  return url.href;
};

console.log(toDevUrl('https://shop.example.com/produkte?id=42'));

// Port wieder entfernen
const u = new URL('http://localhost:3000/health');
u.port = '';
console.log(u.href);

http://localhost:5173/produkte?id=42 http://localhost/health

Tatsächlich verwendeten Port ermitteln

const DEFAULT_PORTS = {
  'http:': 80,
  'https:': 443,
  'ws:': 80,
  'wss:': 443,
  'ftp:': 21,
};

const effectivePort = (href) => {
  const { port, protocol } = new URL(href);
  return port !== '' ? Number(port) : DEFAULT_PORTS[protocol] ?? null;
};

console.log(effectivePort('https://example.com/'));
console.log(effectivePort('wss://chat.example.com:9001/socket'));
console.log(effectivePort('mailto:info@example.com'));

443 9001 null

Verhalten bei ungültigen Werten

const url = new URL('http://example.com:8080/');

url.port = '3000abc'; // nur führende Ziffern zählen
console.log(url.port);

url.port = 'abc';     // keine Ziffern: wird ignoriert
console.log(url.port);

url.port = 70000;     // über 65535: wird ignoriert
console.log(url.port);

url.port = 80;        // Standardport von http:
console.log(JSON.stringify(url.port), url.host);

3000 3000 3000 "" example.com

// Wichtig · Fallstricke

Immer eine Zeichenkette: Vergleiche wie url.port === 8080 sind immer false. Vergleiche mit '8080' oder wandle vorher mit Number(url.port) um.
Leer heißt nicht „kein Port“: "" kann auch bedeuten, dass der Standardport verwendet wird. Den tatsächlichen Port musst du selbst über protocol ermitteln (siehe Beispiel).
Setzen schlägt still fehl: Ungültige Werte, Werte über 65535 sowie URLs ohne Host (z. B. mailto:, data:) oder mit dem Schema file: ignorieren die Zuweisung ohne Fehlermeldung. Prüfe danach bei Bedarf den Wert.
Nur die führenden Ziffern werden übernommen ('8080abc' → '8080'). Das kann Tippfehler in Konfigurationen verbergen. Prüfe Eingaben deshalb vorher, z. B. mit /^\d{1,5}$/.
Ein Port gehört zum origin. Wenn du ihn änderst, gilt die URL als anderer Ursprung, was sich auf CORS und die Same-Origin-Policy auswirkt.
Kompatibilität: Wird von allen modernen Browsern, in Web Workern und in Node.js (global ab v10) unterstützt. location.port und HTMLAnchorElement.port verhalten sich genauso.

Siehe auch

URL URL.host URL.hostname URL.protocol URL.origin URL.href Location.port