Como configurar um proxy para npm com bloqueio de registry: espelhos, .npmrc e como contornar restrições

```html

O npm-registry está indisponível - e a construção do projeto parou. Uma situação familiar para desenvolvedores em redes corporativas, regiões com acesso restrito ou ao trabalhar através de um firewall rigoroso. Neste guia, vamos explorar todas as maneiras de contornar isso: desde a mudança para espelhos até a configuração detalhada do proxy no .npmrc - para que npm install funcione novamente sem erros.

Por que o npm registry é bloqueado e o que acontece com isso

O registro oficial do npm está localizado em https://registry.npmjs.org. Este é um CDN global, mas ainda pode estar indisponível por várias razões, e cada uma requer uma abordagem diferente.

Principais razões para a indisponibilidade do registry

• Firewall corporativo - a empresa bloqueia solicitações diretas a repositórios externos, permitindo tráfego apenas através de um servidor proxy interno. Esta é uma prática padrão em bancos, entidades governamentais e grandes empresas de TI.
• Geobloqueio ou restrições regionais - em vários países e regiões, o acesso ao npmjs.org é restrito ao nível do provedor de internet ou do firewall governamental.
• Rede de escritório sem acesso direto à internet - máquinas de trabalho em segmentos isolados da rede não têm acesso direto a recursos externos, todo o tráfego passa por um gateway corporativo.
• Túnel VPN com proxy forçado - a VPN corporativa redireciona todo o tráfego, e o npm não consegue acessar o registry diretamente.
• Problemas com inspeção SSL - o proxy corporativo intercepta o tráfego HTTPS e substitui os certificados, o que causa erros como SELF_SIGNED_CERT_IN_CHAIN ou UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Erros comuns ao registrar bloqueado

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

Cada um desses códigos de erro indica um problema diferente: ECONNREFUSED - conexão recusada pelo firewall, ETIMEDOUT - solicitação não retorna (bloqueada sem resposta), erros de certificado - problema de inspeção SSL. Compreender a causa imediatamente reduz o escopo das soluções.

Espelhos do npm registry: contorno rápido sem proxy

A maneira mais simples de contornar o bloqueio é mudar o npm para um espelho alternativo do registro. O espelho contém os mesmos pacotes que o registro oficial, mas está localizado em outros servidores e domínios. Isso funciona quando o domínio registry.npmjs.org está bloqueado, e não todo o tráfego HTTPS.

Espelhos populares do npm

Como mudar o registry

Mudança para um único comando (sem alterar as configurações globais):

# Instalação única através do registro alternativo
npm install react --registry https://registry.npmmirror.com

# Instalar globalmente para o usuário atual
npm config set registry https://registry.npmmirror.com

# Verificar o registro atual
npm config get registry

# Retornar ao registro oficial
npm config set registry https://registry.npmjs.org

Um ponto importante: se você mudar para um espelho em um projeto com um comando, é melhor fixar isso no arquivo .npmrc na raiz do repositório - assim todos os membros da equipe receberão automaticamente a configuração correta ao clonar o projeto.

# .npmrc na raiz do projeto
registry=https://registry.npmmirror.com

Configuração de proxy através do .npmrc: sintaxe completa

Quando o espelho não ajuda (por exemplo, quando todo o tráfego HTTPS externo está bloqueado), é necessário especificar explicitamente ao npm o endereço do servidor proxy. O arquivo .npmrc é o principal arquivo de configuração do npm, e é nele que as configurações do proxy são armazenadas.

Localização dos arquivos .npmrc

O npm procura a configuração em vários lugares - na ordem de prioridade (da mais alta para a mais baixa):

• Projeto - /path/to/project/.npmrc - aplica-se apenas a este projeto
• Usuário - ~/.npmrc - aplica-se ao usuário atual do sistema
• Global - $PREFIX/etc/npmrc - aplica-se a toda a instalação do npm
• Incorporado - /path/to/npm/npmrc - configurações padrão do próprio npm

Sintaxe de configuração do proxy no .npmrc

# Proxy para tráfego HTTP
proxy=http://proxy.example.com:8080

# Proxy para tráfego HTTPS (usado para a maioria das solicitações ao registry)
https-proxy=http://proxy.example.com:8080

# Proxy com autenticação (login:senha na URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Exceções - endereços que ignoram o proxy
noproxy=localhost,127.0.0.1,internal.company.com

Instalação do proxy através de comandos npm config

Uma alternativa à edição manual do arquivo é usar o comando npm config set. Ele gravará automaticamente as configurações no ~/.npmrc do usuário:

# Configurar proxy
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Verificar configurações atuais do proxy
npm config get proxy
npm config get https-proxy

# Remover configurações do proxy (retornar à conexão direta)
npm config delete proxy
npm config delete https-proxy

# Visualizar toda a configuração do npm
npm config list

Proxy através de variáveis de ambiente para npm

O npm lê automaticamente as variáveis de ambiente padrão do sistema para proxy. Isso é conveniente em pipelines de CI/CD, contêineres Docker e sistemas onde a configuração é definida no nível do ambiente, e não em arquivos.

Variáveis de ambiente padrão

# Linux / macOS - configuração na sessão atual
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Versões minúsculas (npm entende ambas)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

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

Prioridade da configuração npm

É importante entender que o npm usa a seguinte prioridade ao determinar o proxy (da mais alta para a mais baixa):

1. Flags de linha de comando: --proxy http://...
2. Variáveis de ambiente com o prefixo npm_config_: por exemplo, npm_config_proxy
3. Arquivo de projeto .npmrc
4. Arquivo de usuário ~/.npmrc
5. Arquivo global $PREFIX/etc/npmrc
6. Variáveis de ambiente padrão HTTP_PROXY / HTTPS_PROXY

Se o proxy estiver configurado no .npmrc, mas a variável de ambiente aponta para outro endereço - o .npmrc prevalecerá. Esta é uma causa comum de confusão em sistemas de CI/CD.

Configuração em CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions - adicionar na seção env do job ou 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 - nas variáveis do projeto ou no .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Proxy corporativo com autenticação e inspeção SSL

Servidores proxy corporativos são o caso mais complicado. Eles não apenas redirecionam o tráfego, mas também exigem autenticação, e frequentemente realizam inspeção SSL (interceptação e descriptografia do tráfego HTTPS). Isso gera erros específicos de certificado, com os quais o npm não sabe lidar por padrão.

Proxy com autenticação NTLM/Basic

Se o proxy corporativo exigir login e senha (Autenticação Básica), eles podem ser passados diretamente na URL. No entanto, com autenticação NTLM (domínio Windows), a situação é mais complicada - o npm não suporta NTLM nativamente. Nesse caso, utiliza-se uma ferramenta intermediária.

# Autenticação Básica - login e senha na URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Se a senha contiver caracteres especiais - eles precisam ser URL-encoded
# @ → %40, # → %23, : → %3A
# Exemplo: senha "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Para autenticação NTLM, utiliza-se a ferramenta cntlm - ela é executada localmente, aceita solicitações HTTP normais e realiza o handshake NTLM com o proxy corporativo. Para o npm, isso parece um proxy normal sem autenticação:

# Após configurar o cntlm, ele escuta em localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Solução para problemas de inspeção SSL

Proxies corporativos com inspeção SSL substituem os certificados dos sites pelo seu certificado corporativo. O npm verifica a cadeia de confiança e rejeita tais certificados. Existem três abordagens:

Método 1 (recomendado): adicionar o certificado CA corporativo aos confiáveis

# Obter o certificado corporativo do departamento de TI (arquivo .crt ou .pem)
# Especificá-lo na configuração do npm
npm config set cafile /path/to/corporate-ca.crt

# Ou adicionar vários certificados através do cafile
# É possível combinar vários CAs em um único arquivo PEM

Método 2 (temporário, inseguro): desativar a verificação SSL

# Usar apenas como solução temporária para diagnóstico!
npm config set strict-ssl false

# Ou para um único comando
npm install --legacy-peer-deps --no-strict-ssl

Proxy SOCKS5 para npm: configuração através de utilitários auxiliares

O npm suporta nativamente apenas proxies HTTP/HTTPS. Se você tiver um proxy SOCKS5 (por exemplo, de um provedor de proxies residenciais), ele não pode ser especificado diretamente na configuração do npm. É necessário uma camada intermediária - uma ferramenta que aceita solicitações HTTP do npm e as redireciona através do SOCKS5.

Método 1: proxychains (Linux/macOS)

# Instalação do proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# Configuração /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# Executar npm através do proxychains
proxychains4 npm install

Método 2: conversor local HTTP para SOCKS5

A ferramenta privoxy ou polipo cria um proxy HTTP local que tuneliza o tráfego através do SOCKS5. Após a execução, o npm vê um proxy HTTP normal em localhost:

# Instalação do privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Adicionar na configuração /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# O Privoxy escuta em localhost:8118 por padrão
# Especificar ao npm usar este endereço:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Método 3: túnel SSH como proxy SOCKS5

Se você tiver acesso a um servidor remoto com internet aberta, pode criar um túnel SSH SOCKS5 e redirecionar o tráfego do npm através dele. Isso é especialmente conveniente ao trabalhar a partir de uma rede corporativa com acesso restrito:

# Criar um túnel SSH SOCKS5 na porta local 1080
ssh -D 1080 -f -C -q -N [email protected]

# Em seguida, usar privoxy ou proxychains para converter para HTTP
# Ou diretamente através da variável de ambiente (Node.js entende SOCKS através de algumas bibliotecas)

# Alternativa - usar curl como teste:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Registro privado próprio como alternativa ao proxy

Em ambientes corporativos e isolados, muitas vezes a melhor solução não é configurar um proxy para cada desenvolvedor, mas sim implantar seu próprio npm-registry dentro da rede. Esse registro cacheia pacotes do npmjs.org público e os fornece da rede interna. Os desenvolvedores não precisam de acesso à internet - tudo funciona através do registro local.

Verdaccio: início rápido em 10 minutos

Verdaccio é um npm-registry de código aberto com suporte a proxy e cache. É instalado como um pacote npm, funcionando como um serviço separado:

# Instalação do Verdaccio globalmente
npm install -g verdaccio

# Execução (por padrão escuta em http://localhost:4873)
verdaccio

# Configuração do npm para usar o registro local
npm config set registry http://localhost:4873

# Publicação de pacotes no registro local
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

A configuração do Verdaccio (~/.config/verdaccio/config.yaml) permite configurar o proxy através de um proxy externo para baixar pacotes do npmjs.org:

# config.yaml - configuração uplink com proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Se o Verdaccio estiver atrás de um proxy:
    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

Comparação de soluções para ambientes isolados

Diagnóstico e resolução de erros comuns

Mesmo após a configuração correta, problemas com o proxy podem surgir. Aqui está uma abordagem sistemática para diagnóstico e uma lista dos erros mais comuns com suas soluções.

Passo 1: Verificar a configuração atual do npm

# Mostrar todas as configurações do npm (incluindo proxy)
npm config list

# Mostrar apenas as configurações do proxy
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Ativar saída detalhada para diagnóstico
npm install react --verbose
npm install react --loglevel verbose

Passo 2: Verificar a disponibilidade do registry diretamente

# Verificar a disponibilidade do registry através do curl
curl -v https://registry.npmjs.org/react/latest

# Verificar através do proxy
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Verificar ping (nem sempre informativo para HTTPS)
ping registry.npmjs.org

# Verificar resolução DNS
nslookup registry.npmjs.org

Erros comuns e suas soluções

Redefinir todas as configurações de proxy

# Remover todas as configurações de proxy do config do usuário
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Redefinir o registry para o oficial
npm config set registry https://registry.npmjs.org

# Retornar strict-ssl (se desativado)
npm config set strict-ssl true

# Verificar a configuração final
npm config list

Trabalhando com pnpm e Yarn com o registro bloqueado

Se você estiver usando gerenciadores de pacotes alternativos, a configuração do proxy é semelhante, mas a sintaxe é um pouco diferente:

# pnpm - usa o mesmo .npmrc que o npm
# Adicionalmente, pode ser configurado através do 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) - seu próprio arquivo .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+) - arquivo .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Configuração de proxy para pacotes scoped específicos

Às vezes, é necessário usar registros diferentes para diferentes pacotes: por exemplo, pacotes públicos do npmjs.org oficial, e pacotes corporativos @company/* do Nexus interno. Isso é configurado através do registro específico de escopo no .npmrc:

# .npmrc - registros diferentes para diferentes escopos
registry=https://registry.npmjs.org

# Pacotes corporativos @company através do Nexus interno
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Pacotes @myorg através do Verdaccio
@myorg:registry=http://localhost:4873/

# Autenticação para registro específico
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Conclusão e recomendações finais

Ao longo deste guia, discutimos várias abordagens para contornar bloqueios no npm registry, desde o uso de espelhos até a configuração de proxies. A escolha da solução mais adequada depende do seu ambiente de trabalho e das restrições específicas que você enfrenta. É sempre recomendável documentar as configurações e compartilhar com a equipe para garantir que todos tenham acesso às informações necessárias para um desenvolvimento eficiente.