Sie öffnen auf einem neuen Arbeitslaptop ein Projekt, führen npm install aus, und zwanzig Sekunden lang passiert nichts. Dann erscheint npm error code ETIMEDOUT, gefolgt von dem Hinweis, dass Sie womöglich hinter einem Proxy sitzen. Im Browser auf demselben Rechner öffnet sich die Registry problemlos, denn der Browser nutzt den Firmenproxy, den ihm Windows oder macOS übergibt. npm liest diese Systemeinstellungen nicht. Es braucht eigene.
Dieser Leitfaden zeigt die drei Wege, npm einen Proxy mitzugeben (npm config, .npmrc-Dateien und Umgebungsvariablen), die Reihenfolge, in der npm sie liest, Passwörter mit Sonderzeichen, das Prüfen und Entfernen der Einstellungen, das Ausnehmen interner Hosts vom Proxy und die häufigen Fehler. Jeden Befehl haben wir unter Windows 11 mit Node.js 24.22.2 und npm 11.19.1 ausgeführt, gegen einen lokalen Proxy, der jede Anfrage protokollierte und ein Passwort verlangte, und immer mit einer Wegwerf-Konfigurationsdatei.
Wann braucht npm einen Proxy?
npm braucht einen Proxy immer dann, wenn der Rechner die Registry nicht direkt erreicht oder sie von einer bekannten Adresse aus erreichen muss. Die Registry ist der Server, der die Pakete bereitstellt; für die meisten Projekte ist das https://registry.npmjs.org, eine Firma kann aber auch eine eigene betreiben.
Zwei Situationen decken fast jeden Fall ab. Ein Firmennetz lässt Verkehr nur über einen Proxy hinaus, also läuft eine direkte Verbindung zur Registry in ein Timeout. Oder eine private Registry nimmt Anfragen nur von freigegebenen IP-Adressen an, und Ihr Laptop oder CI-Runner hat keine feste. In beiden Fällen muss npm erfahren, wo der Proxy ist, denn es übernimmt die Proxy-Einstellungen des Betriebssystems nicht so, wie es ein Browser tut.
Wie sendet npm eine Anfrage über einen Proxy?
npm spricht zuerst mit dem Proxy und bittet ihn, einen Tunnel zur Registry zu öffnen. Die folgenden Schritte hat unser protokollierender Proxy während npm view semver version aufgezeichnet:
- npm wählt eine Proxy-Adresse. Es nimmt
https-proxy, falls gesetzt, sonstproxy. Erst wenn beide leer sind, schaut es auf die UmgebungsvariableHTTPS_PROXY. - npm prüft die Ausnahmeliste. Passt der Host der Registry zu einem Eintrag in
noproxy(oderNO_PROXY), wird der Proxy übergangen, und npm verbindet sich direkt. - npm öffnet eine TCP-Verbindung zum Proxy und sendet
CONNECT registry.npmjs.org:443. Enthält die Proxy-Adresse Benutzername und Passwort, schickt npm sie schon mit dieser ersten Anfrage in einemProxy-Authorization-Header. Unser Protokoll zeigte keinen zusätzlichen Umlauf:CONNECT registry.npmjs.org:443 auth user=user (ok). - Der Proxy antwortet mit
200 Connection Establishedund leitet ab dann nur noch Bytes weiter. Der TLS-Handshake läuft innerhalb des Tunnels zwischen npm und der Registry; der Proxy sieht also Hostnamen und Port, nicht die Pakete. - npm lädt Metadaten und Tarballs herunter und legt sie in seinem lokalen Cache ab, was später bei der Fehlersuche wichtig wird.
Wie richten Sie den npm-Proxy ein?
Zwei npm config set-Befehle richten ihn für Ihr Benutzerkonto ein:
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000npm schreibt sie in die benutzereigene .npmrc-Datei (~/.npmrc unter macOS und Linux, C:\Users\<name>\.npmrc unter Windows). Auf unserem Testrechner enthielt die Datei danach genau diese Zeilen:
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000Beachten Sie, dass auch https-proxy mit http:// beginnt. Das Schema beschreibt die Verbindung zum Proxy, nicht die zur Registry: Der Proxy nimmt von npm einfaches HTTP an und trägt den HTTPS-Verkehr im CONNECT-Tunnel. Schreiben Sie https:// nur, wenn der Proxy selbst auf diesem Port TLS erwartet.
Setzen Sie beide Schlüssel. In unserem Test reichte proxy allein für die HTTPS-Registry, weil npm darauf zurückgreift, wenn https-proxy leer ist; nicht jedes Tool, das die Einstellungen von npm liest, kennt aber denselben Rückfall. npm lehnt unbekannte Schlüssel ab, ein Tippfehler wie npm config set proxi … endet also mit npm error `proxi` is not a valid npm option.
Hat der Rechner eine feste IP, können Sie dank der IP-Whitelist von Proxynet die Anmeldedaten ganz aus der URL weglassen: http://pr.proxynet.io:8000 ist dann die gesamte Einstellung.
Welche Einstellungen liest npm, und in welcher Reihenfolge?
npm führt Einstellungen aus mehreren Quellen zusammen, und die spezifischste gewinnt. Die npm-Dokumentation zur Konfiguration nennt als Rangfolge zuerst Befehlszeilenoptionen, dann Umgebungsvariablen, die mit npm_config_ beginnen, dann die .npmrc-Dateien und zuletzt die eingebauten Standardwerte.
| Quelle | Beispiel | Geltungsbereich |
|---|---|---|
| Befehlszeilenoption | --https-proxy http://… | Ein Befehl |
npm_config_*-Variable | npm_config_https_proxy | Aktuelle Shell |
Projekt-.npmrc | <project>/.npmrc | Dieses Projekt |
Benutzer-.npmrc | ~/.npmrc | Ihr Konto |
Globale npmrc | $PREFIX/etc/npmrc | Alle Nutzer dieser Node.js-Installation |
Eingebaute npmrc | im Installationsordner von npm | Diese npm-Kopie |
Wir haben die Reihenfolge mit einer Wegwerfdatei geprüft: npm_config_proxy=http://env.example:3128 überschrieb die Benutzerdatei, und --proxy http://cli.example:3128 überschrieb beide. Bei den Namen der Umgebungsvariablen spielt die Groß- und Kleinschreibung keine Rolle, und Bindestriche werden zu Unterstrichen; aus dem Schlüssel https-proxy wird also npm_config_https_proxy.
Die Option --location von npm config set wählt die Datei: user ist der Standard, project schreibt die .npmrc neben Ihre package.json, und global schreibt die Datei unter dem Präfix von npm. Eine Projekt-.npmrc ist praktisch, wenn nur ein Repository den Proxy braucht, sie wird aber meist in die Versionsverwaltung eingecheckt; Passwörter gehören also nicht hinein. Die .npmrc-Referenz beschreibt außerdem die Ersetzung ${VARIABLE_NAME}: Eine Zeile wie https-proxy=${NPM_PROXY_URL} liest beim Start von npm die vollständige Proxy-URL aus einer Umgebungsvariable und hält so das Geheimnis aus der Datei heraus. Wir haben es getestet; war die Variable nicht gesetzt, ließ npm den wörtlichen Text ${NPM_PROXY_URL} stehen.
Funktionieren HTTP_PROXY und HTTPS_PROXY mit npm?
HTTPS_PROXY funktioniert; HTTP_PROXY allein leitete in unserem Test keinen Registry-Verkehr über den Proxy. Mit gesetztem HTTPS_PROXY und ohne Proxy in irgendeiner .npmrc lief jede Registry-Anfrage über unseren Proxy. Mit nur HTTP_PROXY verband sich npm view direkt, und das Protokoll des Proxys blieb leer, obwohl die Beschreibung von https-proxy in npm selbst HTTP_PROXY als Rückfall nennt. Der Code von npm 11.19.1 liest für https://-Adressen nur HTTPS_PROXY, und die öffentliche Registry läuft über HTTPS.
Das sichere Muster für eine Shell, einen Container oder einen CI-Job: beide setzen, dazu die Ausnahmen.
export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"In Windows PowerShell lauten dieselben Zeilen $env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000" und so weiter. Eine Falle: npm config get https-proxy gibt null aus, auch während HTTPS_PROXY gesetzt ist, weil npm die Variable erst in dem Moment anwendet, in dem es eine Anfrage sendet. Lesen Sie dieses null nicht als „kein Proxy“.
Wie kommen Benutzername und Passwort in die Proxy-URL?
Schreiben Sie beide als user:password@ vor den Host und kodieren Sie jedes Zeichen, das in einer URL eine Bedeutung hat, per Prozentkodierung. Die Prozentkodierung ersetzt ein Zeichen durch % und seinen Hexadezimalcode. Die Zeichen, die eine Proxy-URL zerbrechen, sind die Trennzeichen aus RFC 3986, Abschnitt 2.2: :, /, ?, #, [, ] und @. Auch ein Leerzeichen und % selbst müssen kodiert werden.
| Zeichen | Kodiert |
|---|---|
@ | %40 |
: | %3A |
# | %23 |
/ | %2F |
% | %25 |
| Leerzeichen | %20 |
Unser Testproxy akzeptierte das Passwort p@ss:w#rd. Unkodiert geschrieben, als http://user:p@ss:w#rd@127.0.0.1:18080, erreichte npm den Proxy gar nicht erst: Node.js warnte, die URL sei ungültig, und npm brach mit getaddrinfo ENOTFOUND ss ab. Es hatte den Text nach dem ersten @ als Hostnamen gelesen. Kodiert als http://user:p%40ss%3Aw%23rd@127.0.0.1:18080 lieferte derselbe Befehl die Paketversion, und der Proxy protokollierte eine korrekte Anmeldung. Nennt ein DNS-Fehler einen Host, den Sie nie eingegeben haben, schauen Sie zuerst auf das Passwort.
Wie prüfen und entfernen Sie die npm-Proxy-Einstellungen?
npm config list zeigt jede Einstellung, die vom Standard abweicht, und die Datei, aus der sie stammt. In unserem Lauf begann die Ausgabe mit einer Zeile, die die Quelle nennt, ; "user" config from …\test.npmrc, gefolgt von proxy = "http://user:***@pr.proxynet.io:8000". npm maskiert in dieser Ansicht das Passwort; die Ausgabe lässt sich also gefahrlos in ein Support-Ticket kopieren.
npm config get proxy weigert sich, einen Wert mit Passwort auszugeben: The proxy option is protected, and cannot be retrieved in this way. Ohne Anmeldedaten in der URL gibt der Befehl die Adresse so aus, wie sie gespeichert ist; npm config edit öffnet die Datei selbst.
Um den Proxy zu entfernen, löschen Sie beide Schlüssel:
npm config delete proxy
npm config delete https-proxyJedes delete entfernt eine Zeile aus einer Datei; in unserem Test blieb die Zeile https-proxy stehen, bis sie eigens gelöscht wurde. Ergänzen Sie --location=project oder --location=global für die anderen Dateien, und prüfen Sie HTTPS_PROXY und npm_config_https_proxy in Ihrer Shell, denn eine übrig gebliebene Variable leitet den Verkehr weiter um, auch wenn die Datei sauber ist. Um den Proxy für einen einzelnen Befehl zu umgehen und die Datei zu behalten, geben Sie den Registry-Host als Ausnahme an: --noproxy registry.npmjs.org.
Wie halten Sie bestimmte Hosts vom Proxy fern?
Tragen Sie sie durch Kommas getrennt in noproxy ein. npm vergleicht den Hostnamen Abschnitt für Abschnitt von rechts, daher passt .internal.example auf registry.internal.example und auf jeden anderen Namen unter dieser Domain.
npm config set noproxy "localhost,127.0.0.1,.internal.example"Als wir den Host der öffentlichen Registry in noproxy eintrugen (und in einem zweiten Lauf in NO_PROXY), verband sich npm direkt, und der Proxy protokollierte nichts. Der Schlüssel noproxy übernimmt standardmäßig den Wert von NO_PROXY; führen Sie also eine Liste, nicht zwei verschiedene.
Häufige npm-Proxy-Fehler und ihre Lösungen
Diese Meldungen gab npm 11 in unseren Tests aus, dazu zwei, die wir nicht nachgestellt haben:
npm error code E407mit407 Proxy Authentication Required. Der Proxy verlangt eine Anmeldung und hat keine oder eine falsche erhalten. Ein fehlendes und ein falsches Passwort erzeugten denselben Text. Prüfen Sie den Benutzernamen, die Kodierung der Sonderzeichen und, falls Sie sich darauf verlassen, ob Ihre IP auf der Whitelist steht.getaddrinfo ENOTFOUNDmit einem seltsamen Hostnamen. Die Proxy-URL wurde falsch zerlegt, fast immer wegen eines unkodierten@oder#im Passwort. Ist der genannte Host der Proxy selbst, prüfen Sie die Schreibweise und Ihr DNS.connect ECONNREFUSED <proxy-ip>:<port>. Auf diesem Port lauscht nichts: eine falsche Portnummer, oder der Proxy ist ausgefallen.connect ETIMEDOUT <ip>:<port>. Die Pakete laufen ins Leere; unsere unerreichbare Testadresse scheiterte nach etwa 22 Sekunden. Ist ein Proxy gesetzt, stimmt seine Adresse nicht; ist keiner gesetzt, lässt das Netz Verkehr vermutlich nur über einen Proxy hinaus.ECONNRESET. Die Verbindung wurde geöffnet und dann gekappt, typischerweise von einem Proxy, der lange Downloads beendet, oder von einem Virenscanner, der den Verkehr untersucht.--loglevel verbosezeigt, welche Anfrage gescheitert ist.UNABLE_TO_GET_ISSUER_CERT_LOCALLYoderSELF_SIGNED_CERT_IN_CHAIN. Ein Firmenproxy untersucht HTTPS und signiert es mit seinem eigenen Stammzertifikat neu, dem Node.js nicht vertraut. Legen Sie dieses Stammzertifikat in eine Datei und lassen Sie die npm-Einstellungcafileoder die VariableNODE_EXTRA_CA_CERTSdarauf zeigen; den Unterschied zwischen beiden und wie Sie das richtige Zertifikat finden, erklärt unser Leitfaden zum Fehler mit dem lokalen Ausstellerzertifikat.
strict-ssl=false lässt den letzten Fehler verschwinden, indem es die Zertifikatsprüfung für die Registry abschaltet. Nutzen Sie es höchstens für eine Minute Fehlersuche, nie als Lösung: Damit kann jeder auf dem Netzwerkweg npm ein verändertes Paket unterschieben.
Eine weitere Falle hat uns Zeit gekostet. Mit gefülltem Cache gab npm view eine Version aus, obwohl auf dem Proxy-Port nichts lauschte; npm antwortete aus seinem Cache. Erst mit leerem Cache erschien ECONNREFUSED. Scheint eine Proxy-Änderung zu funktionieren, testen Sie mit einem Paket, das Sie nie installiert haben, oder mit --prefer-online und einem frischen Cache-Ordner über --cache.
Nutzen Yarn und pnpm dieselben Einstellungen?
pnpm liest dieselben .npmrc-Schlüssel, während Yarn ab Version 2 eine eigene Datei nutzt. Die Netzwerkeinstellungen von pnpm beschreiben https-proxy, http-proxy und noproxy, mit dem älteren npm-Schlüssel proxy als Rückfall für beide und danach den Variablen HTTPS_PROXY, HTTP_PROXY und NO_PROXY. pnpm liest aus der .npmrc nur Einstellungen zu Authentifizierung, Registry, TLS, Proxy und local-address; eine bestehende npm-Proxy-Einrichtung lässt sich daher meist unverändert übernehmen.
Yarn ab Version 2 (Yarn Berry) speichert seine Einstellungen in .yarnrc.yml, mit den Schlüsseln httpProxy und httpsProxy, gesetzt zum Beispiel mit yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000. Die Zertifikatsoption heißt httpsCaFilePath, und enableStrictSsl steht standardmäßig auf true, so die Konfigurationsreferenz von Yarn.
Erreicht der Proxy Installationsskripte und Node.js selbst?
Nur teilweise. npm gibt seine Einstellungen als Umgebungsvariablen an Paketskripte weiter: In unserem Test sah ein mit npm run gestartetes Skript npm_config_https_proxy und npm_config_noproxy. Ob ein Skript sie nutzt, entscheidet sein Autor; ein Paket, das während der Installation eine Binärdatei herunterlädt, kann hinter einem Proxy also trotzdem scheitern. Passiert das, nennt die Dokumentation des Pakets meist die Variable, die es liest.
Ihr eigener Node.js-Code ist ein eigenes Thema. Das eingebaute fetch von Node.js ignoriert HTTPS_PROXY, solange der Prozess nicht mit NODE_USE_ENV_PROXY=1 oder dem Schalter --use-env-proxy startet, die aktuelle Node.js-Versionen unterstützen; die Optionen je Bibliothek stehen in Proxys in Node.js verwenden.
Abhängigkeiten, die direkt aus einem Git-Repository installiert werden (eine git+https://-Adresse in package.json), holt Git, nicht der Netzwerkcode von npm. Git hat eigene Proxy-Einstellungen, beschrieben in Git-Proxy-Einstellungen.
Wann hilft eine feste Proxy-IP?
Eine feste Ausgangs-IP hilft, wenn die Registry und nicht Ihr Netz entscheidet, wer sich verbinden darf. Selbst betriebene Registrys und Paketspiegel sind oft durch eine Firewall-Regel geschützt, die eine kurze Liste von Quelladressen zulässt. Build-Agenten in der Cloud erhalten bei jedem Lauf eine neue Adresse, also greift die Regel nie. Leiten Sie npm über einen Proxy mit einer dedizierten, unveränderlichen Adresse, braucht die Firewall nur einen einzigen Eintrag.
Ein Datacenter-Proxy behält dieselbe dedizierte IP, solange Sie ihn behalten, was gut zu Build-Servern passt.
Ein ISP-Proxy leistet dasselbe mit einer Adresse, die auf einen Internetanbieter registriert ist. Beide werden pro IP verkauft und kommen standardmäßig mit einer Zielseiten-Beschränkung; prüfen Sie, ob der Host Ihrer Registry abgedeckt ist, oder buchen Sie die Option „Zugriff auf alle Websites“ hinzu. Hinter einem Firmenproxy gilt nichts davon: Nutzen Sie die Adresse, die Ihnen Ihre IT-Abteilung gibt.
Entscheidungshilfe
| Bedarf | Einstellung |
|---|---|
| Jede Installation auf Ihrem Rechner | npm config set proxy und https-proxy |
| Nur ein Projekt | --location=project, ohne Passwort darin |
| CI-Job oder Container | HTTPS_PROXY plus HTTP_PROXY und NO_PROXY |
| Ein einzelner Befehl | Option --https-proxy |
| Interne Registry direkt erreichen | noproxy mit ihrer Domain |
Passwort mit @ oder # | Prozentkodierung |
| Passwort nicht in Dateien | ${VAR} in .npmrc oder IP-Whitelist |
| Firmenproxy mit TLS-Inspektion | cafile oder NODE_EXTRA_CA_CERTS |
| Registry mit IP-Freigabeliste | Proxy mit dedizierter IP |
Häufige Fragen
Wie richte ich in npm einen Proxy ein?
Führen Sie npm config set proxy http://host:port und npm config set https-proxy http://host:port aus und setzen Sie user:pass@ vor den Host, wenn der Proxy eine Anmeldung verlangt. Die Einstellungen landen in Ihrer Benutzer-.npmrc und gelten ab dann für jeden npm-Befehl.
Wie richte ich einen npm-Proxy mit Benutzername und Passwort ein?
Schreiben Sie beide als http://user:password@host:port in die URL und kodieren Sie Sonderzeichen in beiden Teilen: @ wird zu %40, : zu %3A, # zu %23. Ein unkodiertes @ lässt npm den Rest des Passworts als Hostnamen lesen und mit ENOTFOUND scheitern.
Wie entferne ich den Proxy aus npm?
Führen Sie npm config delete proxy und npm config delete https-proxy aus und prüfen Sie danach mit npm config list. Läuft der Verkehr weiter über einen Proxy, suchen Sie in Ihrer Umgebung nach HTTPS_PROXY oder npm_config_https_proxy und nach einer Projekt- oder globalen .npmrc.
Wo speichert npm die Proxy-Konfiguration?
In einer .npmrc-Datei: standardmäßig pro Benutzer in Ihrem Home-Verzeichnis, pro Projekt neben der package.json oder global unter dem Präfix von npm. npm config list gibt über den Einstellungen jeder gelesenen Datei deren Pfad aus.
Nutzt npm unter Windows den System-Proxy?
Nein. npm liest nur seine eigenen Einstellungen und Umgebungsvariablen, nicht den Proxy aus den Netzwerkeinstellungen von Windows oder aus den Internetoptionen. Tragen Sie dieselbe Adresse mit npm config set oder HTTPS_PROXY ein.
Kann npm einen SOCKS5-Proxy nutzen?
Die Netzwerkschicht von npm enthält einen SOCKS-Client und akzeptiert in den Proxy-Einstellungen Adressen wie socks5://host:port, wie der Quellcode von npm 11 zeigt; gegen einen echten SOCKS-Server haben wir das nicht getestet. Scheitert es bei Ihrer Version, nutzen Sie den HTTP-Endpunkt des Anbieters, über den auch alle Tests in diesem Leitfaden liefen.
Fazit
Geben Sie npm einen Proxy mit npm config set proxy und npm config set https-proxy oder in Shells und CI mit HTTPS_PROXY; HTTP_PROXY allein leitete in unserem Test keinen Registry-Verkehr um. Einstellungen in der Befehlszeile schlagen npm_config_*-Variablen, und diese schlagen die Projekt-, Benutzer- und globalen .npmrc-Dateien. Kodieren Sie Sonderzeichen im Passwort, führen Sie interne Hosts in noproxy, prüfen Sie mit npm config list und entfernen Sie beide Schlüssel mit npm config delete. Zertifikatsfehler hinter einem Firmenproxy brauchen das Stammzertifikat der Firma, nicht strict-ssl=false. Proxy-Endpunkte, die mit all diesen Einstellungen funktionieren, finden Sie auf der Proxy-Seite von Proxynet.




