npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

npm 10 und neuer stellen den Zeilen „npm error“ voran; npm 9 und älter verwendeten „npm ERR!“. Die folgenden Zeilen wiederholen den Code als errno und nennen die URL mit „reason: unable to get local issuer certificate“.

npm (Node.js) — registry request over HTTPS

Was der Fehler bedeutet

npm konnte das TLS-Zertifikat der Registry nicht prüfen: Die erhaltene Kette führt zu einem Root-Zertifikat, das nicht zu den CAs gehört, denen Node.js vertraut. npm läuft auf Node.js, das standardmäßig nur seiner eingebauten Root-Liste von Mozilla vertraut; ein im Betriebssystem installiertes Root-Zertifikat der Firma oder eines Proxys wird deshalb nicht verwendet. Die Anfrage scheitert, bevor ein Paket heruntergeladen wird.

Warum der Fehler auftritt

• Ein Proxy mit TLS-Inspektion signiert registry.npmjs.org neu

  häufig

  In Firmennetzwerken präsentiert der Proxy Zertifikate, die von seiner eigenen CA ausgestellt wurden. Browser vertrauen dieser CA über das Betriebssystem; npm tut das über Node.js nicht.

• Eine private Registry mit Firmenzertifikat

  häufig

  Paket-Registrys von Artifactory, Nexus, Verdaccio oder GitHub Enterprise verwenden oft ein Zertifikat einer internen CA, die nicht in der Root-Liste von Node.js steht.

• Das Root-Zertifikat steht im Trust Store des Betriebssystems, aber Node.js verwendet seine eigene Liste

  gelegentlich

  update-ca-certificates, der macOS-Schlüsselbund und der Windows-Zertifikatsspeicher wirken sich nicht auf Node.js aus, solange Node.js nicht angewiesen wird, den Trust Store des Systems zu verwenden.

So behebst du den Fehler

1. 1.

   cafile von npm setzen

   npm config set cafile verweist npm auf eine PEM-Datei mit den CA-Zertifikaten, denen bei Registry-Anfragen vertraut werden soll (gespeichert in der .npmrc deines Benutzers; --location=project oder --location=global für andere Ebenen). npm vertraut dann nur den CAs in dieser Datei; nimm deshalb auch die öffentlichen Root-Zertifikate auf, wenn npm auch Registrys erreicht, die nicht hinter deiner CA stehen.

   # npm's own setting: a PEM file with the CA(s) to trust for registry requests
   npm config set cafile /etc/ssl/private-ca/corp-root-ca.pem
   npm config get cafile

2. 2.

   NODE_EXTRA_CA_CERTS verwenden

   Die Zertifikate in dieser Datei werden für jeden Node.js-Prozess, der mit der Variablen gestartet wird, zu den eingebauten Root-Zertifikaten von Node.js hinzugefügt, einschließlich npm, npx und Build-Tools.

   # Adds to Node.js's built-in roots for npm and every other Node.js tool in this shell
   export NODE_EXTRA_CA_CERTS=/etc/ssl/private-ca/corp-root-ca.pem
   npm install

3. 3.

   Trust Store des Betriebssystems verwenden

   Mit NODE_USE_SYSTEM_CA=1 (in Node.js-Versionen, die --use-system-ca unterstützen) vertraut npm den Root-Zertifikaten, die die IT im Betriebssystem verteilt hat.

   # Trust what the OS trusts (corporate roots deployed by IT)
   NODE_USE_SYSTEM_CA=1 npm install

4. 4.

   CI: CA über die Umgebung bereitstellen

   Lege das Root-Zertifikat der Firma im Repository ab (es ist öffentlich) oder rufe es im Job ab und setze NODE_EXTRA_CA_CERTS für die Schritte, die npm ausführen.

   # CI job (GitHub Actions syntax): provide the CA to npm without touching the image
   env:
     NODE_EXTRA_CA_CERTS: ${{ github.workspace }}/certs/corp-root-ca.pem
   steps:
     - run: npm ci

5. 5.

   Vorübergehende Diagnose: --strict-ssl=false für einen einzelnen Befehl

   Schaltet die Zertifikatsprüfung für Registry-Anfragen ab. Das bestätigt die Diagnose, erlaubt aber jedem auf dem Übertragungsweg, Pakete auszutauschen, die dann Installationsskripte auf deinem Rechner ausführen; belasse die Einstellung niemals in der .npmrc.

   # Temporary diagnostic for one command only, never in .npmrc
   npm install --strict-ssl=false

← Gesamte Signaturfehler-Datenbank durchsuchen