Proxy no npm: como configurar o npm atrás de um proxy

Publicado:

16 min de leitura

Acar Diveroli
Autor: Acar Diveroli
Janela de terminal com três linhas de .npmrc, a do proxy em azul, e atrás uma janela apagada com uma caixa de registry

Você abre um projeto em um notebook novo do trabalho, roda npm install e nada acontece por vinte segundos. Então aparece npm error code ETIMEDOUT, seguido de uma dica de que você talvez esteja atrás de um proxy. O registry abre normalmente no navegador da mesma máquina, porque o navegador usa o proxy da empresa que o Windows ou o macOS repassa a ele. O npm não lê essas configurações do sistema. Ele precisa das próprias.

Este guia mostra as três formas de dar um proxy ao npm (npm config, arquivos .npmrc e variáveis de ambiente), a ordem em que o npm as lê, senhas com caracteres especiais, como conferir e remover as configurações, como deixar hosts internos fora do proxy e os erros mais comuns. Rodamos cada comando no Windows 11 com Node.js 24.22.2 e npm 11.19.1, contra um proxy local que anotava cada requisição e pedia senha, sempre com um arquivo de configuração descartável.

Quando o npm precisa de um proxy?

O npm precisa de um proxy sempre que a máquina não consegue chegar ao registry diretamente, ou precisa chegar a ele a partir de um endereço conhecido. O registry é o servidor que hospeda os pacotes; para a maioria dos projetos ele é https://registry.npmjs.org, mas uma empresa pode ter o seu próprio.

Duas situações cobrem quase todos os casos. Uma rede corporativa só deixa o tráfego sair por um proxy, e por isso uma conexão direta com o registry entra em timeout. Ou um registry privado aceita requisições apenas de endereços IP liberados, e o seu notebook ou runner de CI não tem um IP fixo. Nos dois casos, é preciso dizer ao npm onde está o proxy, porque ele não aproveita as configurações de proxy do sistema operacional como um navegador faz.

Como o npm envia uma requisição por um proxy?

O npm fala primeiro com o proxy e pede que ele abra um túnel até o registry. Os passos abaixo são o que o nosso proxy de teste anotou durante npm view semver version:

  1. O npm escolhe um endereço de proxy. Ele usa https-proxy, se estiver definido, e senão proxy. Só quando os dois estão vazios ele olha a variável de ambiente HTTPS_PROXY.
  2. O npm confere a lista de exclusão. Se o host do registry corresponder a uma entrada de noproxy (ou NO_PROXY), o proxy é ignorado e o npm se conecta diretamente.
  3. O npm abre uma conexão TCP com o proxy e envia CONNECT registry.npmjs.org:443. Se o endereço do proxy tiver usuário e senha, o npm os manda em um cabeçalho Proxy-Authorization já nessa primeira requisição. O nosso log não mostrou nenhuma ida e volta extra: CONNECT registry.npmjs.org:443 auth user=user (ok).
  4. O proxy responde 200 Connection Established e daí em diante só repassa bytes. O handshake TLS acontece entre o npm e o registry dentro do túnel, então o proxy vê o nome do host e a porta, não os pacotes.
  5. O npm baixa os metadados e os tarballs e os guarda no cache local, o que importa mais tarde na hora de depurar.

Como configurar o proxy do npm?

Dois comandos npm config set configuram o proxy para a sua conta de usuário:

bash
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000

O npm grava os dois no arquivo .npmrc do usuário (~/.npmrc no macOS e no Linux, C:\Users\<name>\.npmrc no Windows). Na nossa máquina de teste, o arquivo ficou depois com exatamente estas linhas:

ini
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000

Repare que https-proxy também começa com http://. O esquema descreve a conexão com o proxy, não com o registry: o proxy recebe HTTP simples do npm e leva o tráfego HTTPS dentro do túnel CONNECT. Escreva https:// apenas se o próprio proxy esperar TLS nessa porta.

Defina as duas chaves. No nosso teste, proxy sozinha bastou para o registry HTTPS, porque o npm recorre a ela quando https-proxy está vazia, mas nem toda ferramenta que lê as configurações do npm aplica a mesma alternativa. O npm rejeita chaves desconhecidas, então um erro de digitação como npm config set proxi … termina com npm error `proxi` is not a valid npm option.

Se a máquina tiver um IP fixo, a whitelist de IP da Proxynet permite deixar as credenciais fora da URL: nesse caso, http://pr.proxynet.io:8000 é a configuração inteira.

Quais configurações o npm lê, e em que ordem?

O npm junta configurações de várias fontes, e a mais específica vence. A documentação de configuração do npm define a prioridade assim: primeiro as opções da linha de comando, depois as variáveis de ambiente que começam com npm_config_, em seguida os arquivos .npmrc e, por último, os padrões embutidos.

FonteExemploAlcance
Opção da linha de comando--https-proxy http://…Um comando
Variável npm_config_*npm_config_https_proxyO shell atual
.npmrc do projeto<project>/.npmrcAquele projeto
.npmrc do usuário~/.npmrcA sua conta
npmrc global$PREFIX/etc/npmrcTodos os usuários daquele Node.js
npmrc embutidona pasta de instalação do npmAquela cópia do npm

Conferimos a ordem com um arquivo descartável: npm_config_proxy=http://env.example:3128 prevaleceu sobre o arquivo do usuário, e --proxy http://cli.example:3128 prevaleceu sobre os dois. Os nomes das variáveis de ambiente não diferenciam maiúsculas de minúsculas, e os hifens viram sublinhados, então a chave https-proxy vira npm_config_https_proxy.

A opção --location de npm config set escolhe o arquivo: user é o padrão, project grava o .npmrc ao lado do seu package.json e global grava o arquivo sob o prefixo do npm. Um .npmrc de projeto é prático quando só um repositório precisa do proxy, mas ele costuma ir para o controle de versão, então não coloque senhas nele. A referência do .npmrc também documenta a substituição ${VARIABLE_NAME}: uma linha como https-proxy=${NPM_PROXY_URL} lê a URL completa do proxy de uma variável de ambiente quando o npm inicia, o que mantém o segredo fora do arquivo. Testamos; com a variável não definida, o npm deixou no lugar o texto literal ${NPM_PROXY_URL}.

HTTP_PROXY e HTTPS_PROXY funcionam com o npm?

HTTPS_PROXY funciona; HTTP_PROXY sozinha não desviou o tráfego do registry no nosso teste. Com HTTPS_PROXY definida e nenhum proxy em nenhum .npmrc, toda requisição ao registry passou pelo nosso proxy. Só com HTTP_PROXY, o npm view se conectou diretamente e o log do proxy ficou vazio, embora a própria descrição de https-proxy no npm cite HTTP_PROXY como alternativa. O código do npm 11.19.1 lê apenas HTTPS_PROXY para endereços https://, e o registry público funciona sobre HTTPS.

O padrão seguro para um shell, um contêiner ou um job de CI é definir as duas, mais as exclusões:

bash
export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"

No Windows PowerShell, as mesmas linhas ficam $env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000" e assim por diante. Uma armadilha: npm config get https-proxy imprime null mesmo com HTTPS_PROXY definida, porque o npm só aplica a variável no momento em que envia uma requisição. Não leia esse null como "sem proxy".

Como colocar usuário e senha na URL do proxy?

Escreva os dois antes do host como user:password@ e aplique codificação percentual a todo caractere que tenha significado em uma URL. A codificação percentual troca um caractere por % e o seu código hexadecimal. Os caracteres que quebram uma URL de proxy são os delimitadores listados na RFC 3986, seção 2.2: :, /, ?, #, [, ] e @. Um espaço e o próprio % também precisam ser codificados.

CaractereCodificado
@%40
:%3A
#%23
/%2F
%%25
espaço%20

O nosso proxy de teste aceitava a senha p@ss:w#rd. Escrita sem codificar, como http://user:p@ss:w#rd@127.0.0.1:18080, o npm nem chegou ao proxy: o Node.js avisou que a URL era inválida, e o npm parou com getaddrinfo ENOTFOUND ss. Ele tinha lido o texto depois do primeiro @ como nome do host. Codificada como http://user:p%40ss%3Aw%23rd@127.0.0.1:18080, o mesmo comando retornou a versão do pacote, e o proxy anotou um login correto. Se um erro de DNS citar um host que você nunca digitou, olhe primeiro para a senha.

Como conferir e remover as configurações de proxy do npm?

npm config list mostra cada configuração diferente do padrão e o arquivo de onde ela veio. Na nossa execução, a saída começava com uma linha que nomeava a origem, ; "user" config from …\test.npmrc, seguida de proxy = "http://user:***@pr.proxynet.io:8000". O npm mascara a senha nessa visualização, o que torna a saída segura para colar em um chamado de suporte.

npm config get proxy se recusa a imprimir um valor que contenha senha: The proxy option is protected, and cannot be retrieved in this way. Sem credenciais na URL, ele imprime o endereço como está gravado; npm config edit abre o próprio arquivo.

Para remover o proxy, apague as duas chaves:

bash
npm config delete proxy
npm config delete https-proxy

Cada delete remove uma linha de um arquivo; no nosso teste, a linha https-proxy continuou lá até ser apagada separadamente. Acrescente --location=project ou --location=global para os outros arquivos, e confira HTTPS_PROXY e npm_config_https_proxy no seu shell, porque uma variável esquecida continua desviando o tráfego depois que o arquivo está limpo. Para pular o proxy em um único comando sem mexer no arquivo, passe o host do registry como exclusão: --noproxy registry.npmjs.org.

Como deixar alguns hosts fora do proxy?

Liste-os em noproxy, separados por vírgulas. O npm compara o nome do host segmento por segmento a partir da direita, então .internal.example corresponde a registry.internal.example e a qualquer outro nome sob esse domínio.

bash
npm config set noproxy "localhost,127.0.0.1,.internal.example"

Quando adicionamos o host do registry público a noproxy (e, em uma segunda execução, a NO_PROXY), o npm se conectou diretamente e o proxy não anotou nada. A chave noproxy assume por padrão o valor de NO_PROXY, então mantenha uma lista só, e não duas diferentes.

Erros comuns de proxy no npm e como corrigir

Estas são as mensagens que o npm 11 mostrou nos nossos testes, mais duas que não reproduzimos:

  • npm error code E407 com 407 Proxy Authentication Required. O proxy quer um login e não recebeu nenhum, ou recebeu um errado. Uma senha ausente e uma senha errada produziram o mesmo texto. Confira o usuário, a codificação dos caracteres especiais e, se você depende dela, se o seu IP está na whitelist.
  • getaddrinfo ENOTFOUND seguido de um nome de host estranho. A URL do proxy foi interpretada errado, quase sempre por causa de um @ ou # sem codificar na senha. Se o host citado for o próprio proxy, confira a grafia e o seu DNS.
  • connect ECONNREFUSED <proxy-ip>:<port>. Nada escuta nessa porta: um número de porta errado, ou o proxy está fora do ar.
  • connect ETIMEDOUT <ip>:<port>. Os pacotes não chegam a lugar nenhum; o nosso endereço de teste inalcançável falhou depois de cerca de 22 segundos. Com um proxy definido, o endereço dele está errado; sem nenhum, a rede provavelmente só deixa o tráfego sair por um proxy.
  • ECONNRESET. A conexão foi aberta e depois cortada, normalmente por um proxy que encerra downloads longos ou por um antivírus que inspeciona o tráfego. --loglevel verbose mostra qual requisição falhou.
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY ou SELF_SIGNED_CERT_IN_CHAIN. Um proxy corporativo inspeciona o HTTPS e o assina de novo com o seu próprio certificado raiz, no qual o Node.js não confia. Coloque esse certificado raiz em um arquivo e aponte para ele a configuração cafile do npm ou a variável NODE_EXTRA_CA_CERTS; a diferença entre as duas, e como achar o certificado certo, está no nosso guia sobre o erro do certificado do emissor local.

strict-ssl=false faz o último erro sumir desligando a verificação de certificados para o registry. Use no máximo por um minuto de depuração, nunca como correção: com ele, qualquer um no caminho da rede pode entregar ao npm um pacote modificado.

Mais uma armadilha nos custou tempo. Com o cache preenchido, o npm view imprimiu uma versão mesmo sem nada escutando na porta do proxy; o npm respondeu a partir do cache. Só com o cache vazio apareceu ECONNREFUSED. Se uma mudança de proxy parecer funcionar, teste com um pacote que você nunca instalou, ou com --prefer-online e uma pasta de cache nova via --cache.

Yarn e pnpm usam as mesmas configurações?

O pnpm lê as mesmas chaves do .npmrc, enquanto o Yarn 2 e versões posteriores usam um arquivo próprio. As configurações de rede do pnpm descrevem https-proxy, http-proxy e noproxy, com a chave antiga proxy do npm como alternativa para as duas e, depois disso, as variáveis HTTPS_PROXY, HTTP_PROXY e NO_PROXY. O pnpm lê do .npmrc apenas as configurações de autenticação, registry, TLS, proxy e local-address, então uma configuração de proxy do npm já existente costuma funcionar sem mudanças.

O Yarn 2 e versões posteriores (Yarn Berry) guardam as configurações em .yarnrc.yml, com as chaves httpProxy e httpsProxy, definidas por exemplo com yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000. A opção de certificado é httpsCaFilePath, e enableStrictSsl vem como true por padrão, segundo a referência de configuração do Yarn.

O proxy chega aos scripts de instalação e ao próprio Node.js?

Só em parte. O npm passa as configurações para os scripts dos pacotes como variáveis de ambiente: no nosso teste, um script iniciado com npm run enxergou npm_config_https_proxy e npm_config_noproxy. Se um script as usa ou não, depende do autor, então um pacote que baixa um binário durante a instalação ainda pode falhar atrás de um proxy. Quando isso acontece, a documentação do próprio pacote costuma indicar a variável que ele lê.

O seu próprio código Node.js é outra história. O fetch embutido do Node.js ignora HTTPS_PROXY, a menos que o processo inicie com NODE_USE_ENV_PROXY=1 ou com a opção --use-env-proxy, que as versões atuais do Node.js suportam; as opções de cada biblioteca estão em Como usar proxy no Node.js.

Dependências instaladas direto de um repositório Git (um endereço git+https:// no package.json) são baixadas pelo Git, não pelo código de rede do npm. O Git tem as próprias configurações de proxy, descritas em Configurar proxy no Git: como usar o Git atrás de um proxy.

Quando um IP de proxy fixo ajuda?

Um IP de saída fixo ajuda quando é o registry, e não a sua rede, que decide quem pode se conectar. Registries auto-hospedados e espelhos de pacotes costumam ser protegidos por uma regra de firewall que libera uma lista curta de endereços de origem. Agentes de build na nuvem recebem um endereço novo a cada execução, então a regra nunca bate. Passar o npm por um proxy com um endereço dedicado e imutável dá ao firewall uma única entrada para liberar.

Os Proxies de datacenter mantêm o mesmo IP dedicado enquanto você o mantiver, o que combina com servidores de build.

Os Proxies ISP fazem o mesmo com um endereço registrado em nome de um provedor de internet. Os dois são vendidos por IP e vêm por padrão com uma restrição de site de destino; confira se o host do seu registry está coberto ou adicione a opção "Acesso a todos os sites". Atrás de um proxy corporativo, nada disso se aplica: use o endereço que a sua equipe de TI passar.

Guia de decisão

NecessidadeConfiguração
Toda instalação na sua máquinanpm config set proxy e https-proxy
Só um projeto--location=project, sem senha nele
Job de CI ou contêinerHTTPS_PROXY mais HTTP_PROXY e NO_PROXY
Um único comandoOpção --https-proxy
Acesso direto ao registry internonoproxy com o domínio dele
Senha com @ ou #Codificação percentual
Senha fora dos arquivos${VAR} no .npmrc ou whitelist de IP
Proxy corporativo com inspeção TLScafile ou NODE_EXTRA_CA_CERTS
Registry que só libera IPs da listaProxy com IP dedicado

Perguntas frequentes

Como configurar um proxy no npm?

Rode npm config set proxy http://host:port e npm config set https-proxy http://host:port, acrescentando user:pass@ antes do host se o proxy pedir login. As configurações vão para o seu .npmrc de usuário e valem a partir daí para todo comando do npm.

Como configurar um proxy no npm com usuário e senha?

Coloque os dois na URL como http://user:password@host:port e codifique os caracteres especiais das duas partes: @ vira %40, : vira %3A e # vira %23. Um @ sem codificar faz o npm ler o resto da senha como nome do host e falhar com ENOTFOUND.

Como remover o proxy do npm?

Rode npm config delete proxy e npm config delete https-proxy e depois confira com npm config list. Se o tráfego ainda passar por um proxy, procure HTTPS_PROXY ou npm_config_https_proxy no seu ambiente e um .npmrc de projeto ou global.

Onde fica a configuração de proxy do npm?

Em um arquivo .npmrc: por padrão, por usuário na sua pasta pessoal; por projeto, ao lado do package.json; ou de forma global, sob o prefixo do npm. npm config list imprime o caminho de cada arquivo lido acima das configurações que vieram dele.

O npm usa o proxy do sistema no Windows?

Não. O npm lê apenas as próprias configurações e as variáveis de ambiente, não o proxy definido nas configurações de rede do Windows nem nas Opções da Internet. Defina o mesmo endereço com npm config set ou HTTPS_PROXY.

O npm pode usar um proxy SOCKS5?

A camada de rede do npm inclui um cliente SOCKS e aceita endereços como socks5://host:port nas configurações de proxy, como mostra o código-fonte do npm 11; não testamos isso contra um servidor SOCKS real. Se falhar na sua versão, use o endpoint HTTP do provedor, que foi o caminho usado em todos os testes deste guia.

Em resumo

Dê um proxy ao npm com npm config set proxy e npm config set https-proxy, ou com HTTPS_PROXY em shells e CI; HTTP_PROXY sozinha não desviou o tráfego do registry no nosso teste. Configurações na linha de comando prevalecem sobre as variáveis npm_config_*, que prevalecem sobre os arquivos .npmrc de projeto, de usuário e global. Codifique os caracteres especiais da senha, mantenha os hosts internos em noproxy, confira com npm config list e remova as duas chaves com npm config delete. Erros de certificado atrás de um proxy corporativo pedem o certificado raiz da empresa, não strict-ssl=false. Os endpoints de proxy que funcionam com todas essas configurações estão na página de proxies da Proxynet.