npm error code UNABLE_TO_GET_ISSUER_CERT_LOCALLY

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-сертификат реестра: полученная цепочка ведёт к корневому сертификату, который не входит в число CA, которым доверяет Node.js. npm работает на Node.js, а тот по умолчанию доверяет только встроенному списку корневых сертификатов Mozilla, поэтому корневой сертификат компании или прокси, установленный в операционной системе, не используется. Запрос завершается ошибкой ещё до того, как скачан хотя бы один пакет.

Почему это происходит

• Прокси с инспекцией TLS переподписывает registry.npmjs.org

  часто

  В корпоративных сетях прокси предъявляет сертификаты, выпущенные его собственным CA. Браузеры доверяют этому CA через ОС, а npm (через Node.js) — нет.

• Частный реестр с корпоративным сертификатом

  часто

  Artifactory, Nexus, Verdaccio или реестры пакетов GitHub Enterprise часто используют сертификат от внутреннего CA, которого нет в списке корневых сертификатов Node.js.

• Корневой сертификат есть в хранилище ОС, но Node.js использует свой список

  иногда

  update-ca-certificates, связка ключей macOS и хранилище сертификатов Windows не влияют на Node.js, пока его не переключат на системное хранилище.

Как исправить

1. 1.

   Задайте cafile в npm

   Команда npm config set cafile указывает npm на PEM-файл с сертификатами CA, которым нужно доверять при запросах к реестру (настройка сохраняется в пользовательском .npmrc; для других уровней используйте --location=project или --location=global). После этого npm доверяет только CA из этого файла, поэтому, если npm обращается и к реестрам с сертификатами не от вашего CA, добавьте в файл и публичные корневые сертификаты.

   # 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 в каждом процессе Node.js, запущенном с этой переменной, включая npm, npx и инструменты сборки.

   # 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 (в версиях Node.js, которые поддерживают --use-system-ca) npm доверяет корневым сертификатам, которые ИТ-отдел развернул в ОС.

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

4. 4.

   CI: передайте CA через окружение

   Добавьте корневой сертификат компании в репозиторий (он не секретный) или скачивайте его в задании и задайте NODE_EXTRA_CA_CERTS для шагов, которые запускают npm.

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

   Временная диагностика: --strict-ssl=false для одной команды

   Флаг отключает проверку сертификатов при запросах к реестру. Он подтверждает диагноз, но позволяет любому на пути трафика подменить пакеты, которые затем запустят скрипты установки на вашей машине; никогда не оставляйте этот параметр в .npmrc.

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

← Открыть всю базу ошибок подписей