本文へスキップ
ecdsa.com
npm (Node.js)パッケージマネージャー

エラーメッセージ

npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

別の表記

  • npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
  • npm error request to https://registry.example.com/lodash failed, reason: unable to get local issuer certificate

npm 10 以降は行頭に「npm error」を付け、npm 9 以前は「npm ERR!」を付けていました。続く行では、コードが errno として繰り返され、URL が「reason: unable to get local issuer certificate」とともに示されます。

npm (Node.js) — registry request over HTTPS

このエラーの意味

npm はレジストリの TLS 証明書を検証できませんでした。受け取ったチェーンが、Node.js の信頼する CA に含まれていないルートにつながっています。npm は Node.js 上で動作し、Node.js はデフォルトで組み込みの Mozilla のルートリストだけを信頼します。そのため、オペレーティングシステムにインストールされた社内やプロキシのルートは使われません。パッケージが 1 つもダウンロードされないうちに、リクエストは失敗します。

発生する理由

修正方法

  1. 1.

    npm の cafile を設定する

    npm config set cafile は、レジストリへのリクエストで信頼する CA 証明書を含む PEM ファイルを npm に指定します（設定はユーザーの .npmrc に保存されます。ほかのスコープには --location=project または --location=global を使います）。設定後の npm はそのファイル内の CA だけを信頼するため、自社の CA の配下にないレジストリにも npm が接続する場合は、パブリックルートも含めてください。

    bash
    # 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 を使う

    この変数を設定して起動したすべての Node.js プロセス（npm、npx、ビルドツールを含む）で、このファイル内の証明書が Node.js の組み込みのルートに追加されます。

    bash
    # 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.

    オペレーティングシステムのトラストストアを使う

    NODE_USE_SYSTEM_CA=1 を設定すると（--use-system-ca に対応した Node.js のバージョンの場合）、npm は IT 部門が OS に配布したルートを信頼します。

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

    CI：環境を通じて CA を渡す

    社内のルート（公開情報です）をコミットするか、ジョブ内で取得し、npm を実行するステップに NODE_EXTRA_CA_CERTS を設定してください。

    yaml
    # 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.

    一時的な診断：1 つのコマンドに限り --strict-ssl=false

    レジストリへのリクエストで証明書の検証を無効にします。診断の裏付けにはなりますが、経路上の誰もがパッケージをすり替えられるようになり、すり替えられたパッケージはマシン上でインストールスクリプトを実行します。.npmrc に残してはいけません。

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

関連するエラー

署名エラーデータベースをすべて見る