Как настроить прокси для npm при блокировке registry: зеркала, .npmrc и обход ограничений

npm-registry недоступен — и сборка проекта встала намертво. Знакомая ситуация для разработчиков в корпоративных сетях, регионах с ограниченным доступом или при работе через строгий файрвол. В этом руководстве разберём все рабочие способы: от переключения на зеркала до тонкой настройки прокси в .npmrc — чтобы npm install снова работал без ошибок.

Почему npm registry блокируется и что происходит при этом

Официальный реестр npm расположен по адресу https://registry.npmjs.org. Это глобальный CDN, но он всё равно может быть недоступен по нескольким причинам, и каждая требует своего подхода.

Основные причины недоступности registry

• Корпоративный файрвол — компания блокирует прямые запросы к внешним репозиториям, разрешая трафик только через внутренний прокси-сервер. Это стандартная практика в банках, госструктурах, крупных IT-компаниях.
• Геоблокировка или региональные ограничения — в ряде стран и регионов доступ к npmjs.org ограничен на уровне интернет-провайдера или государственного файрвола.
• Офисная сеть без прямого выхода в интернет — рабочие машины в изолированных сегментах сети не имеют прямого доступа к внешним ресурсам, весь трафик проходит через корпоративный шлюз.
• VPN-туннель с принудительным проксированием — корпоративный VPN перенаправляет весь трафик, и npm не может достучаться до registry напрямую.
• Проблемы с SSL-инспекцией — корпоративный прокси перехватывает HTTPS-трафик и подменяет сертификаты, что вызывает ошибки вида SELF_SIGNED_CERT_IN_CHAIN или UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Типичные ошибки при заблокированном 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

Каждый из этих кодов ошибки указывает на разную проблему: ECONNREFUSED — соединение отклонено файрволом, ETIMEDOUT — запрос уходит в никуда (заблокирован без ответа), ошибки сертификатов — проблема SSL-инспекции. Понимание причины сразу сужает круг решений.

Зеркала npm registry: быстрый обход без прокси

Самый простой способ обойти блокировку — переключить npm на альтернативное зеркало реестра. Зеркало содержит те же пакеты, что и официальный registry, но расположено на других серверах и доменах. Это работает, когда заблокирован именно домен registry.npmjs.org, а не весь HTTPS-трафик.

Популярные зеркала npm

Как переключить registry

Переключение для одной команды (без изменения глобальных настроек):

# Разовая установка через альтернативный registry
npm install react --registry https://registry.npmmirror.com

# Установить глобально для текущего пользователя
npm config set registry https://registry.npmmirror.com

# Проверить текущий registry
npm config get registry

# Вернуть официальный registry
npm config set registry https://registry.npmjs.org

Важный нюанс: если вы переключаетесь на зеркало в проекте с командой, лучше зафиксировать это в файле .npmrc в корне репозитория — тогда все члены команды автоматически получат правильную конфигурацию при клонировании проекта.

# .npmrc в корне проекта
registry=https://registry.npmmirror.com

Настройка прокси через .npmrc: полный синтаксис

Когда зеркало не помогает (например, заблокирован весь внешний HTTPS-трафик), нужно явно указать npm адрес прокси-сервера. Файл .npmrc — главный конфигурационный файл npm, и именно в нём хранятся настройки прокси.

Расположение файлов .npmrc

npm ищет конфигурацию в нескольких местах — в порядке приоритета (от высшего к низшему):

• Проектный — /path/to/project/.npmrc — применяется только к этому проекту
• Пользовательский — ~/.npmrc — применяется для текущего пользователя системы
• Глобальный — $PREFIX/etc/npmrc — применяется для всей установки npm
• Встроенный — /path/to/npm/npmrc — дефолтные настройки самого npm

Синтаксис настройки прокси в .npmrc

# Прокси для HTTP-трафика
proxy=http://proxy.example.com:8080

# Прокси для HTTPS-трафика (используется для большинства запросов к registry)
https-proxy=http://proxy.example.com:8080

# Прокси с аутентификацией (логин:пароль в URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Исключения — адреса, которые обходят прокси
noproxy=localhost,127.0.0.1,internal.company.com

Установка прокси через команды npm config

Альтернатива ручному редактированию файла — использование команды npm config set. Она автоматически запишет настройки в пользовательский ~/.npmrc:

# Установить прокси
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Проверить текущие настройки прокси
npm config get proxy
npm config get https-proxy

# Удалить настройки прокси (вернуть прямое подключение)
npm config delete proxy
npm config delete https-proxy

# Просмотреть весь конфиг npm
npm config list

Прокси через переменные окружения для npm

npm автоматически читает стандартные системные переменные окружения для прокси. Это удобно в CI/CD-пайплайнах, Docker-контейнерах и системах, где конфигурация задаётся на уровне окружения, а не файлов.

Стандартные переменные окружения

# Linux / macOS — установка в текущей сессии
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Строчные варианты (npm понимает оба)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Command Prompt)
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"

Приоритет конфигурации npm

Важно понимать, что npm использует следующий приоритет при определении прокси (от высшего к низшему):

1. Флаги командной строки: --proxy http://...
2. Переменные окружения с префиксом npm_config_: например, npm_config_proxy
3. Проектный .npmrc
4. Пользовательский ~/.npmrc
5. Глобальный $PREFIX/etc/npmrc
6. Стандартные переменные окружения HTTP_PROXY / HTTPS_PROXY

Если прокси настроен в .npmrc, но переменная окружения указывает на другой адрес — выиграет .npmrc. Это частая причина путаницы в CI/CD-системах.

Настройка в CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions — добавить в env секцию job или step
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 — в переменных проекта или в .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Корпоративный прокси с аутентификацией и SSL-инспекцией

Корпоративные прокси-серверы — самый сложный случай. Они не просто перенаправляют трафик, но и требуют аутентификации, а также нередко выполняют SSL-инспекцию (перехват и расшифровку HTTPS-трафика). Это порождает специфические ошибки сертификатов, с которыми npm не умеет работать из коробки.

Прокси с аутентификацией NTLM/Basic

Если корпоративный прокси требует логин и пароль (Basic Auth), их можно передать прямо в URL. Однако с NTLM-аутентификацией (Windows-домен) всё сложнее — npm не поддерживает NTLM нативно. В этом случае используют промежуточный инструмент.

# Basic Auth — логин и пароль в URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Если пароль содержит спецсимволы — их нужно URL-энкодировать
# @ → %40, # → %23, : → %3A
# Пример: пароль "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Для NTLM-аутентификации используют утилиту cntlm — она запускается локально, принимает обычные HTTP-запросы и сама выполняет NTLM-хендшейк с корпоративным прокси. Для npm это выглядит как обычный прокси без аутентификации:

# После настройки cntlm он слушает на localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Решение проблемы SSL-инспекции

Корпоративные прокси с SSL-инспекцией подменяют сертификаты сайтов своим корпоративным сертификатом. npm проверяет цепочку доверия и отвергает такие сертификаты. Есть три подхода:

Способ 1 (рекомендуется): добавить корпоративный CA-сертификат в доверенные

# Получить корпоративный сертификат у IT-отдела (файл .crt или .pem)
# Указать его в конфигурации npm
npm config set cafile /path/to/corporate-ca.crt

# Или добавить несколько сертификатов через cafile
# Можно объединить несколько CA в один PEM-файл

Способ 2 (временный, небезопасный): отключить проверку SSL

# Использовать только как временное решение для диагностики!
npm config set strict-ssl false

# Или для одной команды
npm install --legacy-peer-deps --no-strict-ssl

SOCKS5-прокси для npm: настройка через helper-утилиты

npm нативно поддерживает только HTTP/HTTPS-прокси. Если у вас есть SOCKS5-прокси (например, от провайдера резидентных прокси), его нельзя указать напрямую в конфиге npm. Нужен промежуточный слой — утилита, которая принимает HTTP-запросы от npm и перенаправляет их через SOCKS5.

Способ 1: proxychains (Linux/macOS)

# Установка proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# Конфигурация /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# Запуск npm через proxychains
proxychains4 npm install

Способ 2: локальный HTTP-к-SOCKS5 конвертер

Утилита privoxy или polipo создаёт локальный HTTP-прокси, который туннелирует трафик через SOCKS5. После запуска npm видит обычный HTTP-прокси на localhost:

# Установка privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Добавить в конфиг /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# Privoxy слушает на localhost:8118 по умолчанию
# Указать npm использовать этот адрес:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Способ 3: SSH-туннель как SOCKS5-прокси

Если у вас есть доступ к удалённому серверу с открытым интернетом, можно создать SSH SOCKS5-туннель и направить через него трафик npm. Это особенно удобно при работе из корпоративной сети с ограниченным доступом:

# Создать SSH SOCKS5-туннель на локальном порту 1080
ssh -D 1080 -f -C -q -N [email protected]

# Далее использовать privoxy или proxychains для конвертации в HTTP
# Или напрямую через переменную окружения (Node.js понимает SOCKS через некоторые либы)

# Альтернатива — использовать curl как тест:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Собственный приватный registry как альтернатива прокси

В корпоративных и изолированных окружениях часто лучшим решением является не настройка прокси для каждого разработчика, а развёртывание собственного npm-registry внутри сети. Такой registry кеширует пакеты из публичного npmjs.org и отдаёт их из внутренней сети. Разработчикам не нужен доступ к интернету — всё работает через локальный registry.

Verdaccio: быстрый старт за 10 минут

Verdaccio — опенсорсный npm-registry с поддержкой проксирования и кеширования. Устанавливается как npm-пакет, работает как отдельный сервис:

# Установка Verdaccio глобально
npm install -g verdaccio

# Запуск (по умолчанию слушает на http://localhost:4873)
verdaccio

# Настройка npm для использования локального registry
npm config set registry http://localhost:4873

# Публикация пакетов в локальный registry
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

Конфигурация Verdaccio (~/.config/verdaccio/config.yaml) позволяет настроить проксирование через внешний прокси для загрузки пакетов из npmjs.org:

# config.yaml — настройка uplink с прокси
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Если Verdaccio сам находится за прокси:
    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

Сравнение решений для изолированных сред

Диагностика и устранение типичных ошибок

Даже после правильной настройки прокси могут возникать проблемы. Вот систематический подход к диагностике и список наиболее частых ошибок с их решениями.

Шаг 1: Проверить текущую конфигурацию npm

# Показать все настройки npm (включая прокси)
npm config list

# Показать только настройки прокси
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Включить подробный вывод для диагностики
npm install react --verbose
npm install react --loglevel verbose

Шаг 2: Проверить доступность registry напрямую

# Проверить доступность registry через curl
curl -v https://registry.npmjs.org/react/latest

# Проверить через прокси
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Проверить ping (не всегда информативно для HTTPS)
ping registry.npmjs.org

# Проверить DNS-разрешение
nslookup registry.npmjs.org

Типичные ошибки и их решения

Сброс всех настроек прокси

# Удалить все настройки прокси из пользовательского конфига
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Сбросить registry на официальный
npm config set registry https://registry.npmjs.org

# Вернуть strict-ssl (если отключали)
npm config set strict-ssl true

# Проверить итоговый конфиг
npm config list

Работа с pnpm и Yarn при заблокированном registry

Если вы используете альтернативные пакетные менеджеры, настройка прокси выглядит аналогично, но синтаксис немного отличается:

# pnpm — использует тот же .npmrc, что и npm
# Дополнительно можно настроить через pnpm config:
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) — свой .yarnrc файл
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+) — файл .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Настройка прокси для конкретных scoped-пакетов

Иногда нужно использовать разные registry для разных пакетов: например, публичные пакеты брать из официального npmjs.org, а корпоративные @company/* — из внутреннего Nexus. Это настраивается через scope-specific registry в .npmrc:

# .npmrc — разные registry для разных scope
registry=https://registry.npmjs.org

# Корпоративные пакеты @company через внутренний Nexus
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Пакеты @myorg через Verdaccio
@myorg:registry=http://localhost:4873/

# Аутентификация для конкретного registry
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Заключение и итоговые рекомендации