So richten Sie einen Proxy für npm ein, wenn das Registry blockiert ist: Mirrors, .npmrc und Umgehung von Einschränkungen

```html

npm-registry ist nicht verfügbar – und der Aufbau des Projekts steht still. Eine vertraute Situation für Entwickler in Unternehmensnetzwerken, Regionen mit eingeschränktem Zugang oder bei der Arbeit über eine strenge Firewall. In diesem Leitfaden werden wir alle funktionierenden Methoden durchgehen: vom Wechsel zu Mirrors bis zur feinen Konfiguration des Proxys in .npmrc – damit npm install wieder ohne Fehler funktioniert.

Warum wird das npm registry blockiert und was passiert dabei?

Das offizielle npm-Registry befindet sich unter https://registry.npmjs.org. Es handelt sich um ein globales CDN, aber es kann aus verschiedenen Gründen nicht verfügbar sein, und jeder Grund erfordert einen eigenen Ansatz.

Hauptursachen für die Nichterreichbarkeit des registries

• Unternehmensfirewall – das Unternehmen blockiert direkte Anfragen an externe Repositories und erlaubt den Datenverkehr nur über einen internen Proxy-Server. Dies ist eine gängige Praxis in Banken, staatlichen Institutionen und großen IT-Unternehmen.
• Geoblocking oder regionale Einschränkungen – in einigen Ländern und Regionen ist der Zugang zu npmjs.org auf Ebene des Internetanbieters oder der staatlichen Firewall eingeschränkt.
• Büro-Netzwerk ohne direkten Internetzugang – Arbeitsmaschinen in isolierten Netzwerksegmenten haben keinen direkten Zugang zu externen Ressourcen, der gesamte Datenverkehr erfolgt über das Unternehmensgateway.
• VPN-Tunnel mit erzwungener Proxyschaltung – das Unternehmens-VPN leitet den gesamten Datenverkehr um, und npm kann nicht direkt auf das registry zugreifen.
• Probleme mit der SSL-Inspektion – der Unternehmensproxy fängt HTTPS-Datenverkehr ab und ersetzt Zertifikate, was zu Fehlern wie SELF_SIGNED_CERT_IN_CHAIN oder UNABLE_TO_VERIFY_LEAF_SIGNATURE führt.

Typische Fehler bei blockiertem registry

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

Jeder dieser Fehlercodes weist auf ein anderes Problem hin: ECONNREFUSED – Verbindung wurde von der Firewall abgelehnt, ETIMEDOUT – Anfrage geht ins Leere (blockiert ohne Antwort), Zertifikatfehler – Problem mit der SSL-Inspektion. Das Verständnis der Ursache schränkt sofort den Lösungsbereich ein.

Mirrors des npm registries: schneller Umgehung ohne Proxy

Der einfachste Weg, die Blockierung zu umgehen, besteht darin, npm auf ein alternatives Mirror des registries umzustellen. Das Mirror enthält dieselben Pakete wie das offizielle registry, ist jedoch auf anderen Servern und Domains gehostet. Dies funktioniert, wenn nur die Domain registry.npmjs.org blockiert ist und nicht der gesamte HTTPS-Datenverkehr.

Beliebte Mirrors für npm

Wie man das registry wechselt

Wechsel für einen Befehl (ohne globale Einstellungen zu ändern):

# Einmalige Installation über ein alternatives registry
npm install react --registry https://registry.npmmirror.com

# Global für den aktuellen Benutzer installieren
npm config set registry https://registry.npmmirror.com

# Aktuelles registry überprüfen
npm config get registry

# Offizielles registry zurücksetzen
npm config set registry https://registry.npmjs.org

Ein wichtiger Punkt: Wenn Sie in einem Projekt zu einem Mirror wechseln, ist es besser, dies in der Datei .npmrc im Stammverzeichnis des Repositories zu fixieren – dann erhalten alle Teammitglieder automatisch die richtige Konfiguration beim Klonen des Projekts.

# .npmrc im Stammverzeichnis des Projekts
registry=https://registry.npmmirror.com

Proxy-Konfiguration über .npmrc: vollständige Syntax

Wenn das Mirror nicht hilft (z.B. wenn der gesamte externe HTTPS-Datenverkehr blockiert ist), muss npm ausdrücklich die Adresse des Proxy-Servers angegeben werden. Die Datei .npmrc ist die Hauptkonfigurationsdatei für npm, und hier werden die Proxy-Einstellungen gespeichert.

Standorte der .npmrc-Dateien

npm sucht die Konfiguration an mehreren Stellen – in der Reihenfolge der Priorität (von hoch nach niedrig):

• Projekt – /path/to/project/.npmrc – gilt nur für dieses Projekt
• Benutzer – ~/.npmrc – gilt für den aktuellen Benutzer des Systems
• Global – $PREFIX/etc/npmrc – gilt für die gesamte npm-Installation
• Integriert – /path/to/npm/npmrc – Standardkonfiguration von npm selbst

Syntax zur Proxy-Konfiguration in .npmrc

# Proxy für HTTP-Datenverkehr
proxy=http://proxy.example.com:8080

# Proxy für HTTPS-Datenverkehr (wird für die meisten Anfragen an das registry verwendet)
https-proxy=http://proxy.example.com:8080

# Proxy mit Authentifizierung (Benutzername:Passwort in der URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Ausnahmen – Adressen, die den Proxy umgehen
noproxy=localhost,127.0.0.1,internal.company.com

Proxy über npm config-Befehle einstellen

Eine Alternative zur manuellen Bearbeitung der Datei ist die Verwendung des Befehls npm config set. Dieser schreibt die Einstellungen automatisch in die Benutzerdatei ~/.npmrc:

# Proxy einstellen
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Aktuelle Proxy-Einstellungen überprüfen
npm config get proxy
npm config get https-proxy

# Proxy-Einstellungen löschen (direkte Verbindung wiederherstellen)
npm config delete proxy
npm config delete https-proxy

# Gesamte npm-Konfiguration anzeigen
npm config list

Proxy über Umgebungsvariablen für npm

npm liest automatisch die Standard-Systemumgebungsvariablen für Proxys. Dies ist praktisch in CI/CD-Pipelines, Docker-Containern und Systemen, in denen die Konfiguration auf der Ebene der Umgebung und nicht über Dateien festgelegt wird.

Standard-Umgebungsvariablen

# Linux / macOS – Einstellung in der aktuellen Sitzung
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Kleinbuchstaben-Varianten (npm versteht beide)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Eingabeaufforderung)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

Priorität der npm-Konfiguration

Es ist wichtig zu verstehen, dass npm die folgende Priorität bei der Bestimmung des Proxys verwendet (von hoch nach niedrig):

1. CLI-Flags: --proxy http://...
2. Umgebungsvariablen mit dem Präfix npm_config_: z.B. npm_config_proxy
3. Projekt .npmrc
4. Benutzer ~/.npmrc
5. Global $PREFIX/etc/npmrc
6. Standard-Umgebungsvariablen HTTP_PROXY / HTTPS_PROXY

Wenn der Proxy in .npmrc konfiguriert ist, aber die Umgebungsvariable auf eine andere Adresse verweist – gewinnt .npmrc. Dies ist ein häufiger Grund für Verwirrung in CI/CD-Systemen.

Konfiguration in CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions – in die env-Sektion des Jobs oder Schrittes einfügen
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI – in den Projektvariablen oder in .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Unternehmensproxy mit Authentifizierung und SSL-Inspektion

Unternehmensproxies sind der komplizierteste Fall. Sie leiten den Datenverkehr nicht nur um, sondern erfordern auch eine Authentifizierung und führen häufig eine SSL-Inspektion durch (Abfangen und Entschlüsseln von HTTPS-Datenverkehr). Dies führt zu spezifischen Zertifikatfehlern, mit denen npm nicht von Haus aus umgehen kann.

Proxy mit NTLM/Basic-Authentifizierung

Wenn der Unternehmensproxy einen Benutzernamen und ein Passwort benötigt (Basic Auth), können diese direkt in die URL eingefügt werden. Bei NTLM-Authentifizierung (Windows-Domain) ist es komplizierter – npm unterstützt NTLM nicht nativ. In diesem Fall wird ein Zwischentool verwendet.

# Basic Auth – Benutzername und Passwort in der URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Wenn das Passwort Sonderzeichen enthält – diese müssen URL-encodiert werden
# @ → %40, # → %23, : → %3A
# Beispiel: Passwort "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Für die NTLM-Authentifizierung wird das Tool cntlm verwendet – es wird lokal ausgeführt, akzeptiert normale HTTP-Anfragen und führt selbst den NTLM-Handshake mit dem Unternehmensproxy durch. Für npm sieht dies aus wie ein normaler Proxy ohne Authentifizierung:

# Nach der Einrichtung von cntlm hört es auf localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Lösung des SSL-Inspektionsproblems

Unternehmensproxies mit SSL-Inspektion ersetzen die Zertifikate von Websites durch ihr Unternehmenszertifikat. npm überprüft die Vertrauenskette und lehnt solche Zertifikate ab. Es gibt drei Ansätze:

Ansatz 1 (empfohlen): Unternehmens-CA-Zertifikat zu den vertrauenswürdigen hinzufügen

# Unternehmenszertifikat beim IT-Team anfordern (Datei .crt oder .pem)
# In der npm-Konfiguration angeben
npm config set cafile /path/to/corporate-ca.crt

# Oder mehrere Zertifikate über cafile hinzufügen
# Mehrere CAs können in einer PEM-Datei zusammengeführt werden

Ansatz 2 (vorübergehend, unsicher): SSL-Überprüfung deaktivieren

# Nur als vorübergehende Lösung zur Diagnose verwenden!
npm config set strict-ssl false

# Oder für einen Befehl
npm install --legacy-peer-deps --no-strict-ssl

SOCKS5-Proxy für npm: Einrichtung über Helper-Utilities

npm unterstützt nativ nur HTTP/HTTPS-Proxys. Wenn Sie einen SOCKS5-Proxy haben (z.B. von einem Anbieter residential proxies), kann dieser nicht direkt in der npm-Konfiguration angegeben werden. Es ist eine Zwischenschicht erforderlich – ein Tool, das HTTP-Anfragen von npm akzeptiert und sie über SOCKS5 umleitet.

Ansatz 1: proxychains (Linux/macOS)

# Installation von proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# Konfiguration /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# npm über proxychains ausführen
proxychains4 npm install

Ansatz 2: Lokaler HTTP-zu-SOCKS5-Konverter

Das Tool privoxy oder polipo erstellt einen lokalen HTTP-Proxy, der den Datenverkehr über SOCKS5 tunnelt. Nach dem Start sieht npm einen normalen HTTP-Proxy unter localhost:

# Installation von privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# In die Konfiguration /etc/privoxy/config hinzufügen:
forward-socks5 / proxy.example.com:1080 .

# Privoxy hört standardmäßig auf localhost:8118
# npm anweisen, diese Adresse zu verwenden:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Ansatz 3: SSH-Tunnel als SOCKS5-Proxy

Wenn Sie Zugang zu einem Remote-Server mit offenem Internet haben, können Sie einen SSH SOCKS5-Tunnel erstellen und den Datenverkehr von npm darüber leiten. Dies ist besonders praktisch, wenn Sie aus einem Unternehmensnetzwerk mit eingeschränktem Zugang arbeiten:

# SSH SOCKS5-Tunnel auf lokalem Port 1080 erstellen
ssh -D 1080 -f -C -q -N [email protected]

# Danach privoxy oder proxychains verwenden, um in HTTP zu konvertieren
# Oder direkt über die Umgebungsvariable (Node.js versteht SOCKS über einige Bibliotheken)

# Alternative – curl als Test verwenden:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Eigenes privates registry als Alternative zum Proxy

In Unternehmens- und isolierten Umgebungen ist oft die beste Lösung nicht die Einrichtung eines Proxys für jeden Entwickler, sondern die Bereitstellung eines eigenen npm-registries innerhalb des Netzwerks. Dieses registry cached Pakete aus dem öffentlichen npmjs.org und stellt sie aus dem internen Netzwerk bereit. Entwickler benötigen keinen Zugang zum Internet – alles funktioniert über das lokale registry.

Verdaccio: schneller Start in 10 Minuten

Verdaccio ist ein Open-Source-npm-registry mit Unterstützung für Proxy und Caching. Es wird als npm-Paket installiert und läuft als separater Dienst:

# Verdaccio global installieren
npm install -g verdaccio

# Starten (hört standardmäßig auf http://localhost:4873)
verdaccio

# npm für die Verwendung des lokalen registries konfigurieren
npm config set registry http://localhost:4873

# Pakete im lokalen registry veröffentlichen
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Die Verdaccio-Konfiguration (~/.config/verdaccio/config.yaml) ermöglicht die Konfiguration des Proxys über einen externen Proxy zum Herunterladen von Paketen aus npmjs.org:

# config.yaml – uplink-Konfiguration mit Proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Wenn Verdaccio selbst hinter einem Proxy steht:
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

Vergleich von Lösungen für isolierte Umgebungen

Diagnose und Behebung typischer Fehler

Selbst nach der richtigen Proxy-Konfiguration können Probleme auftreten. Hier ist ein systematischer Ansatz zur Diagnose und eine Liste der häufigsten Fehler mit ihren Lösungen.

Schritt 1: Aktuelle npm-Konfiguration überprüfen

# Alle npm-Einstellungen anzeigen (einschließlich Proxy)
npm config list

# Nur die Proxy-Einstellungen anzeigen
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Detaillierte Ausgabe zur Diagnose aktivieren
npm install react --verbose
npm install react --loglevel verbose

Schritt 2: Verfügbarkeit des registries direkt überprüfen

# Verfügbarkeit des registries über curl überprüfen
curl -v https://registry.npmjs.org/react/latest

# Über den Proxy überprüfen
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Ping überprüfen (nicht immer informativ für HTTPS)
ping registry.npmjs.org

# DNS-Auflösung überprüfen
nslookup registry.npmjs.org

Typische Fehler und ihre Lösungen

Alle Proxy-Einstellungen zurücksetzen

# Alle Proxy-Einstellungen aus der Benutzereinstellung löschen
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Registry auf das offizielle zurücksetzen
npm config set registry https://registry.npmjs.org

# strict-ssl zurücksetzen (falls deaktiviert)
npm config set strict-ssl true

# Endgültige Konfiguration überprüfen
npm config list

Arbeiten mit pnpm und Yarn bei blockiertem registry

Wenn Sie alternative Paketmanager verwenden, sieht die Proxy-Konfiguration ähnlich aus, aber die Syntax ist etwas anders:

# pnpm – verwendet dasselbe .npmrc wie npm
# Zusätzlich über pnpm config einstellen:
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) – eigene .yarnrc-Datei
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) – Datei .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Proxy für bestimmte scoped-Pakete konfigurieren

Manchmal müssen unterschiedliche registries für verschiedene Pakete verwendet werden: z.B. öffentliche Pakete aus dem offiziellen npmjs.org beziehen, während Unternehmenspakete @company/* aus dem internen Nexus stammen. Dies wird über ein scope-spezifisches registry in .npmrc konfiguriert:

# .npmrc – unterschiedliche registries für unterschiedliche scopes
registry=https://registry.npmjs.org

# Unternehmenspakete @company über internen Nexus
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Pakete @myorg über Verdaccio
@myorg:registry=http://localhost:4873/

# Authentifizierung für spezifisches registry
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Fazit und abschließende Empfehlungen

Um die oben genannten Probleme zu lösen, sollten Entwickler die verschiedenen Ansätze zur Proxy-Konfiguration und die Verwendung von Mirrors in Betracht ziehen. Die Implementierung eines eigenen registries kann eine langfristige Lösung für Unternehmen sein, die regelmäßig auf npm zugreifen müssen, während sie gleichzeitig Sicherheits- und Zugangsanforderungen einhalten.