ERR_INVALID_URL in Node.js beheben

Was verursacht ERR_INVALID_URL?

Der Fehler ERR_INVALID_URL (formell TypeError [ERR_INVALID_URL]: Invalid URL) wird von Node.js ausgelöst, wenn der URL-Konstruktor oder die veraltete Funktion url.parse() eine Zeichenkette erhält, die nicht als gültige URL geparst werden kann. Dieser Fehler tritt häufig bei der Verarbeitung von Benutzereingaben, beim Parsen von Konfigurationsdateien oder beim Umgang mit URLs aus externen Quellen auf.

Der URL-Konstruktor folgt dem WHATWG-URL-Standard, der strenger ist als das ältere RFC-basierte Parsen. Eine Zeichenkette muss ein gültiges Schema (wie https:), eine gültige Autorität (Hostname) sowie korrekt formatierte Pfad- und Query-Komponenten enthalten, um als gültige URL akzeptiert zu werden.

// Dies löst ERR_INVALID_URL aus
try {
  const url = new URL('not-a-url');
} catch (err) {
  console.log(err.code);    // 'ERR_INVALID_URL'
  console.log(err.message); // 'Invalid URL: not-a-url'
  console.log(err.input);   // 'not-a-url'
}

Häufige Ursachen und Lösungen

Ursache 1: Fehlendes Protokoll/Schema. Der URL-Konstruktor benötigt ein Schema wie https:// oder http://. Zeichenketten wie example.com/path oder www.example.com schlagen fehl.

// FEHLER: kein Protokoll
new URL('example.com/path');  // ERR_INVALID_URL

// LÖSUNG: das Protokoll hinzufügen
new URL('https://example.com/path');  // Funktioniert!

// LÖSUNG: Protokoll hinzufügen, falls es fehlt
function ensureProtocol(urlString) {
  if (!/^https?:\/\//i.test(urlString)) {
    return 'https://' + urlString;
  }
  return urlString;
}
new URL(ensureProtocol('example.com/path'));  // Funktioniert!

Ursache 2: Nicht kodierte Sonderzeichen. Zeichen wie Leerzeichen, geschweifte Klammern, senkrechte Striche und bestimmte Unicode-Zeichen sind in URLs ohne Kodierung nicht zulässig.

// FEHLER: nicht kodierte Leerzeichen und Sonderzeichen
new URL('https://example.com/my file.pdf');    // ERR_INVALID_URL
new URL('https://example.com/path?q=a b');     // Kann in manchen Versionen fehlschlagen

// LÖSUNG: die problematischen Teile kodieren
const filename = encodeURIComponent('my file.pdf');
new URL('https://example.com/' + filename);    // Funktioniert!

// LÖSUNG: encodeURI für eine vollständige URL mit Leerzeichen verwenden
const rawUrl = 'https://example.com/my file.pdf';
new URL(encodeURI(rawUrl));  // Funktioniert!

Ursache 3: Fehlerhafte Prozentkodierung. Wenn eine URL ein Prozentzeichen enthält, auf das nicht genau zwei Hexadezimalziffern folgen, weist der Parser sie zurück.

// FEHLER: fehlerhafte Prozentkodierung
new URL('https://example.com/100%done');       // ERR_INVALID_URL
new URL('https://example.com/path?q=50%');     // ERR_INVALID_URL

// LÖSUNG: das einzelne Prozentzeichen als %25 kodieren
function fixPercentSigns(urlString) {
  return urlString.replace(/%(?![0-9A-Fa-f]{2})/g, '%25');
}
new URL(fixPercentSigns('https://example.com/100%done'));
// Funktioniert! Die URL wird zu https://example.com/100%25done

Ursache 4: Leere oder null-Eingabe. Auch das Übergeben einer leeren Zeichenkette, von null oder undefined an den URL-Konstruktor löst diesen Fehler aus.

// FEHLER: leere oder null-Eingabe
new URL('');           // ERR_INVALID_URL
new URL(null);         // ERR_INVALID_URL
new URL(undefined);    // ERR_INVALID_URL

// LÖSUNG: die Eingabe vor dem Parsen validieren
function parseUrl(input) {
  if (!input || typeof input !== 'string') {
    return null;
  }
  try {
    return new URL(input);
  } catch {
    return null;
  }
}

Ursache 5: Relative URLs ohne Basis. Der URL-Konstruktor behandelt das erste Argument standardmäßig als absolute URL. Relative URLs wie /path/to/page benötigen eine Basis-URL als zweites Argument.

// FEHLER: relative URL ohne Basis
new URL('/api/users');  // ERR_INVALID_URL

// LÖSUNG: eine Basis-URL angeben
new URL('/api/users', 'https://example.com');
// Funktioniert! → https://example.com/api/users

// Nützliches Muster für API-Clients
const BASE_URL = 'https://api.example.com';
const endpoint = new URL('/v2/users?page=1', BASE_URL);
console.log(endpoint.href);
// "https://api.example.com/v2/users?page=1"

URLs vor dem Parsen validieren

Die zuverlässigste Methode, eine URL in Node.js zu validieren, besteht darin, den URL-Konstruktor in einem try-catch-Block zu verwenden. Es gibt keine eingebaute Methode URL.isValid() (Stand Node.js 22), daher ist das Abfangen des Fehlers der übliche Ansatz.

// Einfacher URL-Validator
function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch {
    return false;
  }
}

console.log(isValidUrl('https://example.com'));  // true
console.log(isValidUrl('not-a-url'));            // false
console.log(isValidUrl(''));                     // false

// Validator mit erlaubten Protokollen
function isValidHttpUrl(string) {
  try {
    const url = new URL(string);
    return url.protocol === 'http:' || url.protocol === 'https:';
  } catch {
    return false;
  }
}

console.log(isValidHttpUrl('https://example.com'));     // true
console.log(isValidHttpUrl('ftp://example.com'));       // false
console.log(isValidHttpUrl('javascript:alert(1)'));     // false

Sicheres Muster zum Parsen von URLs

Hier ist ein robustes Muster zum Parsen von URLs, das alle häufigen Fehlerfälle behandelt und ein geparstes URL-Objekt oder einen aussagekräftigen Fehler zurückgibt.

class UrlParser {
  static parse(input, base) {
    // Eingabe validieren
    if (!input || typeof input !== 'string') {
      return { ok: false, error: 'Input must be a non-empty string' };
    }

    // Leerzeichen entfernen
    const trimmed = input.trim();

    // Häufige Probleme beheben
    let urlString = trimmed;

    // Protokoll hinzufügen, falls es fehlt
    if (/^[a-zA-Z0-9]/.test(urlString) && !urlString.includes('://')) {
      urlString = 'https://' + urlString;
    }

    // Einzelne Prozentzeichen korrigieren
    urlString = urlString.replace(/%(?![0-9A-Fa-f]{2})/g, '%25');

    try {
      const url = base ? new URL(urlString, base) : new URL(urlString);

      // Optional: auf sichere Protokolle beschränken
      if (!['http:', 'https:'].includes(url.protocol)) {
        return { ok: false, error: 'Unsupported protocol: ' + url.protocol };
      }

      return { ok: true, url };
    } catch (err) {
      return { ok: false, error: err.message };
    }
  }
}

// Verwendung
const result = UrlParser.parse('example.com/path?q=hello world');
if (result.ok) {
  console.log(result.url.href);
} else {
  console.error(result.error);
}

Bewährte Praktiken zur Vorbeugung

Die Befolgung dieser Praktiken hilft Ihnen, ERR_INVALID_URL-Fehler in Ihren Node.js-Anwendungen zu vermeiden und eine robustere URL-Verarbeitung aufzubauen.

• Umschließen Sie das Parsen von URLs immer mit try-catch. Gehen Sie nie davon aus, dass eine URL-Zeichenkette gültig ist, insbesondere wenn sie aus Benutzereingaben, Umgebungsvariablen, Datenbanken oder externen APIs stammt.
• Verwenden Sie die URL-API statt String-Verkettung. Erstellen Sie URLs mit dem URL-Konstruktor und URLSearchParams, statt Zeichenketten zu verketten. Die API übernimmt die Kodierung automatisch.
• Validieren Sie Umgebungsvariablen beim Start. Wenn Ihre Anwendung URLs aus Umgebungsvariablen oder Konfigurationsdateien liest, validieren Sie sie beim Start der Anwendung und nicht erst bei der ersten Verwendung.
• Kodieren Sie Benutzereingaben, bevor Sie sie in URLs einbetten. Verwenden Sie immer encodeURIComponent() für Werte von Query-Parametern und encodeURI() für vollständige, von Benutzern bereitgestellte URLs.
• Verwenden Sie einen URL-Builder für komplexe Fälle. Erstellen Sie zum Aufbau von URLs mit vielen dynamischen Teilen eine Hilfsfunktion oder Klasse, die die Kodierung konsistent handhabt.
• Protokollieren Sie bei Fehlern die ursprüngliche Eingabe. Wenn Sie einen ERR_INVALID_URL-Fehler abfangen, protokollieren Sie die Eingabe, die ihn verursacht hat (bereinigt, falls sie sensible Daten enthalten könnte), um das Problem leichter zu beheben.

// Gute Praxis: Konfigurations-URLs beim Start validieren
const requiredUrls = ['API_BASE_URL', 'AUTH_SERVER_URL', 'WEBHOOK_URL'];

for (const envVar of requiredUrls) {
  const value = process.env[envVar];
  if (!value) {
    throw new Error(envVar + ' environment variable is required');
  }
  try {
    new URL(value);
  } catch {
    throw new Error(envVar + ' is not a valid URL: ' + value);
  }
}

// Gute Praxis: die URL-API zum Erstellen von URLs verwenden
function buildApiUrl(endpoint, params) {
  const url = new URL(endpoint, process.env.API_BASE_URL);
  for (const [key, value] of Object.entries(params)) {
    url.searchParams.set(key, String(value));
  }
  return url.toString();
}

const searchUrl = buildApiUrl('/api/search', {
  q: 'Node.js & Express',
  page: 1
});
// "https://api.example.com/api/search?q=Node.js+%26+Express&page=1"