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:
- O npm escolhe um endereço de proxy. Ele usa
https-proxy, se estiver definido, e senãoproxy. Só quando os dois estão vazios ele olha a variável de ambienteHTTPS_PROXY. - O npm confere a lista de exclusão. Se o host do registry corresponder a uma entrada de
noproxy(ouNO_PROXY), o proxy é ignorado e o npm se conecta diretamente. - 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çalhoProxy-Authorizationjá nessa primeira requisição. O nosso log não mostrou nenhuma ida e volta extra:CONNECT registry.npmjs.org:443 auth user=user (ok). - O proxy responde
200 Connection Establishede 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. - 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:
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000O 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:
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000Repare 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.
| Fonte | Exemplo | Alcance |
|---|---|---|
| Opção da linha de comando | --https-proxy http://… | Um comando |
Variável npm_config_* | npm_config_https_proxy | O shell atual |
.npmrc do projeto | <project>/.npmrc | Aquele projeto |
.npmrc do usuário | ~/.npmrc | A sua conta |
npmrc global | $PREFIX/etc/npmrc | Todos os usuários daquele Node.js |
npmrc embutido | na pasta de instalação do npm | Aquela 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:
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.
| Caractere | Codificado |
|---|---|
@ | %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:
npm config delete proxy
npm config delete https-proxyCada 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.
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 E407com407 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 ENOTFOUNDseguido 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 verbosemostra qual requisição falhou.UNABLE_TO_GET_ISSUER_CERT_LOCALLYouSELF_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çãocafiledo npm ou a variávelNODE_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
| Necessidade | Configuração |
|---|---|
| Toda instalação na sua máquina | npm config set proxy e https-proxy |
| Só um projeto | --location=project, sem senha nele |
| Job de CI ou contêiner | HTTPS_PROXY mais HTTP_PROXY e NO_PROXY |
| Um único comando | Opção --https-proxy |
| Acesso direto ao registry interno | noproxy 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 TLS | cafile ou NODE_EXTRA_CA_CERTS |
| Registry que só libera IPs da lista | Proxy 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.




