Como Configurar um Proxy no Axios para Node.js (Sim, Inclusive HTTPS)

Em algum canto do Stack Overflow, neste exato momento, alguém está convencido de que o Axios “quebra silenciosamente” com proxies HTTPS. Essa é uma das queixas mais repetidas em tutoriais de proxy para Node.js, e não descreve a versão atual testada neste guia. Montei um ambiente local de testes com origens HTTP e HTTPS reais atrás de dois proxies, e o Axios 1.19.0 encaminhou a requisição HTTPS por meio de um CONNECT adequado, em vez de simplesmente ignorar o proxy.

Isso não quer dizer que a dor que as pessoas relatam seja inventada. Versões antigas do Axios tinham bugs reais (veja issue #3384 e issue #4531), e versões recentes do Node adicionaram uma segunda rota de proxy via ambiente que exige configuração cuidadosa. Este guia mostra o que realmente funciona no Axios 1.19.0 hoje, todas as formas de encaixar um proxy nas suas requisições, um padrão de rotação com interceptors que quase nenhum tutorial mostra, e uma tabela completa de erro → correção para quando algo sair dos trilhos.

O que é um proxy no Axios (e por que isso importa no Node.js)?

No contexto do Axios, um proxy é só um servidor intermediário entre o seu processo Node e o site de destino. A sua requisição vai primeiro para o proxy, o proxy repassa para o destino, e o site enxerga o IP do proxy em vez do seu. É basicamente isso.

Os desenvolvedores usam isso por vários motivos: fazer scraping de sites que limitam taxa ou bloqueiam por IP, testar como um app se comporta em outra região, direcionar tráfego por um ponto de saída corporativo ou simplesmente manter o IP do próprio servidor fora dos logs de acesso do alvo. A configuração oficial de requisição do Axios oferece uma opção proxy nativa com campos host, port, protocol e auth — ela existe há anos e é a primeira coisa que todo tutorial mostra, incluindo este.

Aqui está o ponto que costuma ser simplificado demais: essa opção proxy se comporta de forma diferente dependendo de você estar acessando um destino HTTP ou HTTPS, e também da versão do Axios em execução. Essa diferença é justamente o motivo deste guia existir.

Configurando Node.js e Axios (base rápida)

Pule esta parte se você já tem um projeto rodando. Caso contrário, leva cerca de dois minutos.

mkdir axios-proxy-demo && cd axios-proxy-demo
npm init -y
npm install axios

Adicione "type": "module" ao seu package.json se quiser usar imports ESM (eu prefiro — require() do CommonJS em um demo de proxy já soa antigo). A versão LTS atual do Node é v24.18.0, embora eu tenha executado os testes especificamente no v22.22.3 para que os resultados não dependessem das peculiaridades da runtime mais recente.

Coloque isto em app.js e execute node app.js:

import axios from 'axios';

const res = await axios.get('https://httpbin.org/ip');
console.log(res.data);

Você deverá ver o seu IP real na resposta. Esse é o seu ponto de comparação — quando o proxy estiver funcionando, a mesma requisição deve retornar o IP do proxy.

Registre essa resposta antes de ativar o proxy; isso cria uma referência concreta para comparar com a requisição roteada no próximo passo.

O Axios realmente suporta proxies HTTPS? (vamos acertar isso)

Resposta curta: sim, na versão estável atual. O Axios 1.19.0 documenta o tunneling CONNECT para alvos HTTPS atrás de um proxy HTTP. A API de downloads do npm registrou 117.890.039 downloads do Axios entre 31 de julho e 6 de agosto de 2026, um indicador datado de o quanto a biblioteca é usada. Quando você acessa uma URL HTTPS por meio de um proxy, o Axios atual envia uma requisição CONNECT para abrir o túnel, e o handshake TLS acontece ponta a ponta com a origem real. Eu testei isso diretamente: proxy HTTP local, origem HTTPS local com certificado autoassinado, e o contador de CONNECT no meu proxy subiu exatamente como esperado.

Então por que “Axios HTTPS proxy broken” aparece em praticamente todo tópico de fórum sobre isso? Por alguns motivos, e todos são reais:

Versões antigas do Axios. As issues do GitHub que as pessoas citam muitas vezes têm anos de idade e descrevem comportamentos específicos de determinada versão e configuração, que não devem ser generalizados para o Axios atual.
Servidores de proxy sem suporte a CONNECT. Nesse cenário, o túnel falha e o Axios deve expor um erro; capture o caminho real e o erro antes de concluir que houve bypass do IP.
Confusão entre proxy e algo que ele não é. A opção proxy é uma instrução de forward proxy, não um botão genérico de “roteie tudo por este agent, custe o que custar”.

O Chromium informou em 2023 que mais de 90% das navegações do Chrome nas principais plataformas usavam HTTPS. Essa é uma medição datada do Chrome, não um censo atual de toda a web, mas explica por que o comportamento com destinos HTTPS precisa estar no centro deste tutorial. Se você estiver preso em uma versão antiga do Axios, reproduza o problema na linha atual antes de assumir que um bug histórico ainda descreve o comportamento presente; teste a atualização no seu próprio aplicativo antes de colocá-la em produção.

Quando você ainda quer um agent explícito

A configuração nativa proxy funciona bem para um único proxy estático e convencional. Mas ela perde força no momento em que você precisa de controle por requisição, rotação de proxy ou suporte a SOCKS — a opção embutida do Axios simplesmente não foi feita para isso. É aí que o HttpsProxyAgent faz sentido, e eu mostro isso abaixo. Pense na opção nativa como “boa o suficiente para um proxy, um objetivo” e na abordagem com agent como “o que você realmente quer em produção”.

O caminho de proxy via ambiente no Node v24 e v22.21+

Versões recentes do Node trazem um modo nativo de proxy via ambiente, ativado por NODE_USE_ENV_PROXY=1 ou pela flag --use-env-proxy. Segundo a documentação oficial da CLI do Node, isso chegou no v24.0.0 e foi retroportado para o v22.21.0 — então “Node 22+” está tecnicamente errado; é especificamente v22.21.0 e posteriores dentro dessa linha. Se você estiver em um patch anterior do Node 22, essa flag simplesmente não existe.

O Axios atual já resolve HTTP_PROXY, HTTPS_PROXY e NO_PROXY por meio da dependência proxy-from-env, então global-agent não é necessário para esse caminho atual do Axios. Quando o modo de proxy via ambiente do próprio Node também está ativo, duas camadas podem participar da decisão de roteamento.

A documentação do Axios observa que, em versões do Node nas quais o agent carrega a propriedade proxyEnv, o Axios passa a usar o tratamento do Node em vez de fazer a resolução sozinho. Na prática, isso significa que você deve escolher um sistema e manter essa decisão:

Deixar o Node cuidar disso: ative a flag, não configure proxy no Axios e deixe as variáveis de ambiente fazerem o trabalho.
Deixar o Axios cuidar disso: não ative a flag do Node e deixe a resolução de variáveis de ambiente do próprio Axios entrar em ação.
Assumir controle total manualmente: defina proxy: false explicitamente e forneça o seu próprio httpsAgent — isso contorna totalmente os dois sistemas automáticos, o que eu recomendo assim que você precisar de rotação ou lógica por requisição.

Eu testei diretamente a resolução do lado do Axios: definir HTTP_PROXY no ambiente de um processo filho roteou a requisição pelo meu proxy local, e adicionar uma entrada correspondente em NO_PROXY fez a próxima requisição ignorá-lo corretamente. Então o caminho por variáveis de ambiente realmente funciona pronto para uso agora — o ponto de atenção é o cenário de dupla camada.

5 maneiras de encaixar um proxy no Axios (comparativo)

Antes de ir para o código, vale ver o panorama. Montei e testei cada uma dessas opções em uma configuração real de proxy local, não apenas lendo a documentação.

Método	Suporte a HTTPS	Suporte a autenticação	Controle por requisição	Adequado para rotação	Complexidade
Opção `proxy` embutida	✅ (Axios atual)	✅	✅	❌	Baixa
Padrões em `axios.create()`	✅ (Axios atual)	✅	❌ (vale para a instância toda)	❌	Baixa
Variáveis de ambiente (`HTTP_PROXY`/`HTTPS_PROXY`)	✅	✅	❌	❌	Baixa
`httpsAgent` + `HttpsProxyAgent`	✅	✅	✅	⚠️ (manual)	Média
Interceptor de requisição + pool de agents	✅	✅	✅	✅	Média-alta

Use a opção embutida para um script rápido que chama um único proxy. Use axios.create() quando todas as requisições de um módulo devem passar pelo mesmo proxy sem repetir configuração. Use variáveis de ambiente quando o time de infraestrutura já gerencia o roteamento centralmente e você só quer herdar isso. Recorra a um agent explícito quando precisar de um controle que a configuração nativa não oferece — e recorra ao padrão com interceptor assim que “controle” virar “rotação”.

Three Axios proxy routing methods converging on an HTTPS destination

Passo a passo: configuração básica de proxy no Axios

A configuração mais simples usa o objeto proxy embutido diretamente na requisição:

import axios from 'axios';

const res = await axios.get('https://httpbin.org/ip', {
  proxy: {
    host: '203.0.113.10',
    port: 8080,
    protocol: 'http',
  },
});

console.log(res.data);

Execute isso e você deverá ver o IP do proxy na resposta, em vez do seu próprio. Se você estiver testando localmente com um proxy real, isso normalmente resolve em bem menos de um segundo — comparado, por exemplo, a configurar manualmente um proxy no sistema só para testar uma requisição, aquele tipo de tarefa que consome quinze minutos que você não tem.

Compare essa resposta com a linha de base. Um teste bem-sucedido deve mostrar o IP público do proxy, e não o IP de origem que você registrou antes.

Usando `axios.create()` para padrões na instância inteira

Se todas as requisições de um determinado módulo devem passar pelo mesmo proxy, coloque isso em uma instância em vez de repetir a configuração:

const client = axios.create({
  proxy: {
    host: '203.0.113.10',
    port: 8080,
  },
  timeout: 15_000,
});

const res = await client.get('https://httpbin.org/ip');

Eu confirmei que sobrescrever com proxy: false em uma requisição individual ignora o padrão da instância sem problemas — útil quando 95% das chamadas precisam de proxy, mas algumas poucas (como um ping de health check) não devem usar.

Definindo proxy via variáveis de ambiente

Para roteamento gerenciado centralmente — pense em containers Docker ou ambientes de CI onde o time de operações já define variáveis de proxy — você nem precisa mexer na configuração do Axios:

export HTTP_PROXY=http://203.0.113.10:8080
export HTTPS_PROXY=http://203.0.113.10:8080
export NO_PROXY=localhost,127.0.0.1

O Axios atual lê essas variáveis sem global-agent. Só lembre da fronteira de versão do Node mencionada acima: se NODE_USE_ENV_PROXY também estiver ativo, deixe claro quem é o responsável pelo roteamento e teste o comportamento de NO_PROXY no runtime que vai para produção.

Passo a passo: configuração de proxy HTTPS com `httpsAgent` (para controle real)

Essa é a configuração que eu realmente recomendaria quando você precisa de algo além de “um proxy, para sempre”. Instale o pacote de agent atual:

npm install https-proxy-agent

A versão 9.1.0 do https-proxy-agent exige Node 20 ou superior e envia um CONNECT adequado ao seu proxy antes de encaminhar a conexão do destino por ele.

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://203.0.113.10:8080');

const client = axios.create({
  proxy: false,        // impede que a resolução nativa do Axios também entre na jogada
  httpsAgent: agent,
  timeout: 15_000,
});

const res = await client.get('https://httpbin.org/ip');
console.log(res.data);

Defina proxy: false quando um agent explícito for o dono do roteamento. Isso torna a configuração inequívoca e impede que a resolução nativa ou via ambiente do Axios concorra com o agent fornecido.

Adicionando autenticação ao proxy

Inclua as credenciais diretamente na URL do proxy:

const agent = new HttpsProxyAgent('http://myuser:mypassword@203.0.113.10:8080');

Se a sua senha tiver caracteres especiais — @, : e # são os mais chatos — faça percent-encoding antes de montar a URL, ou construa a string com encodeURIComponent() em cada componente. Um @ bruto na senha será interpretado como início da seção do host, e você acabará com um erro de conexão sem nenhuma relação óbvia com encoding.

Usando proxies SOCKS5 com Axios

Proxies SOCKS não são compatíveis com HttpsProxyAgent — você precisa de um agent diferente para esse protocolo:

npm install socks-proxy-agent

import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5://myuser:mypass@203.0.113.10:1080');

const client = axios.create({
  proxy: false,
  httpsAgent: agent,
});

O socks-proxy-agent 10.1.0 também exige Node 20+. SOCKS5 vale a pena quando você trabalha com redes corporativas que expõem apenas um gateway SOCKS, ou com provedores de proxy que oferecem suporte de protocolo mais flexível do que os proxies HTTP simples permitem.

Rotacionando proxies com interceptors de requisição do Axios

Escolher um proxy aleatório dentro do código da chamada funciona bem para um script pontual. Isso desmorona quando você faz centenas de requisições, porque não existe um ponto central monitorando quais proxies morreram, não há lógica de retry e o código de seleção de proxy acaba copiado em todo lugar. O sistema de interceptors do Axios dá um lar testável para essa lógica; nenhum dos cinco tutoriais concorrentes avaliados na SERP deste artigo usou esse padrão.

Axios GET requests rotating across three proxies with one bounded retry

Montando um pool de proxies

import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

class ProxyPool {
  private agents: HttpsProxyAgent<string>[];
  private index = 0;

  constructor(proxyUrls: string[]) {
    this.agents = proxyUrls.map((url) => new HttpsProxyAgent(url));
  }

  next(): HttpsProxyAgent<string> {
    const agent = this.agents[this.index];
    this.index = (this.index + 1) % this.agents.length;
    return agent;
  }
}

const pool = new ProxyPool([
  'http://user:pass@proxy1.example.com:8080',
  'http://user:pass@proxy2.example.com:8080',
]);

const client = axios.create({ timeout: 15_000 });

client.interceptors.request.use((config: InternalAxiosRequestConfig) => {
  config.proxy = false;
  config.httpsAgent = pool.next();
  return config;
});

Eu executei isso contra dois proxies locais e confirmei que as requisições alternavam corretamente — proxy A, depois proxy B, depois de volta ao A. Observe que o Axios executa interceptors de requisição em ordem last-in-first-out, então, se você tiver outros interceptors (headers de autenticação, logs), a ordem importa mais do que parece.

Adicionando um interceptor de resposta com proteção de retry

É aqui que a maioria dos scripts caseiros de rotação fica bagunçada. Tentar novamente cegamente em qualquer falha, contra um pool ilimitado, pode transformar uma requisição ruim numa cascata de problemas — especialmente em métodos não idempotentes como POST, nos quais repetir a requisição pode duplicar um efeito colateral que você definitivamente não queria duplicar.

type RetryableConfig = InternalAxiosRequestConfig & {
  __proxyRetryCount?: number;
};

client.interceptors.response.use(
  undefined,
  async (error: AxiosError) => {
    const config = error.config as RetryableConfig | undefined;
    if (!config) throw error;

    const method = String(config.method ?? 'get').toUpperCase();
    config.__proxyRetryCount ??= 0;
    if (method !== 'GET' || config.__proxyRetryCount >= 1) throw error;

    config.__proxyRetryCount += 1;
    config.proxy = false;
    config.httpsAgent = pool.next();
    return client.request(config);
  }
);

Eu testei isso contra um proxy propositalmente quebrado e confirmei que exatamente uma tentativa de retry foi disparada no agent alternativo — sem loop infinito, sem retry em uma requisição POST. Esse é o limite que você quer: uma política de retry honesta sobre quais requisições podem ser repetidas, e não um truque de “tenta de novo até funcionar”.

Axios proxy troubleshooting with cURL, 407 authentication, and timeout checks

Tabela de diagnóstico de erros: mapeie cada falha para a correção

Salve esta seção. São os erros que realmente aparecem em issues do GitHub do Axios e em tópicos do Stack Overflow, não os hipotéticos.

Erro / Sintoma	Causa provável	Correção
`ECONNREFUSED`	Host/porta incorretos, ou o servidor proxy está fora do ar	Verifique com `curl -x http://host:port target-url` antes de mexer no código do Axios
`407 Proxy Authentication Required`	Credenciais ausentes ou incorretas	Adicione `auth: { username, password }` à configuração `proxy`, ou incorpore as credenciais na URL do `HttpsProxyAgent`
`403 Forbidden`	A origem ou o WAF rejeitou a requisição ou o IP do proxy	Verifique a política de acesso, autenticação e taxa de requisição do site; não trate um header diferente ou outro IP como permissão para contornar restrições
A resposta mostra seu IP real	`NO_PROXY`, `proxy:false`, um agent direto explícito ou uma configuração histórica/específica de versão pode estar ignorando o proxy	Inspecione qual camada é a dona do roteamento; valide o caminho com um endpoint de IP controlado e, se necessário, um agent explícito
`ETIMEDOUT`	O intervalo de conexão ou de resposta excedeu o timeout configurado	Meça onde o tempo está sendo gasto; ajuste o timeout apenas se o trabalho justificar, caso contrário substitua ou esfrie a rota ruim
`ECONNRESET` no meio da resposta	O proxy, a rede ou a origem encerrou a conexão	Registre qual salto falhou; faça retry apenas em requisições seguras de repetir, com orçamento finito
`502 Bad Gateway` atrás do Nginx	O `proxy_pass` do Nginx está mal configurado, ou o timeout do Axios não combina com o do Nginx	Verifique `proxy_connect_timeout` e `proxy_read_timeout` (ambos têm padrão de 60s) e alinhe com o `timeout` do Axios
`ERR_TLS_CERT_ALTNAME_INVALID`	Tipo de agent errado para o destino, ou certificado autoassinado	Confirme que você está usando o agent certo para o protocolo; use `rejectUnauthorized: false` apenas em testes locais — nunca em produção

Checklist rápido de depuração

Quando algo quebrar e você não souber o motivo, siga esta ordem:

Teste o proxy diretamente com curl -x http://host:port https://your-target.com. Se falhar, investigue conectividade do proxy, autenticação e o destino antes de alterar o Axios. Se funcionar, o caminho do Axios ainda precisa de verificação separada.
Confirme quais versões de Axios e Node você realmente está executando e compare relatos históricos na mesma versão/configuração antes de aplicar as correções deles.
Descubra qual sistema está resolvendo o proxy — configuração nativa do Axios, resolução via variáveis de ambiente do Axios, modo de proxy embutido do Node ou um agent explícito. Nunca deixe mais de um ser dono da mesma requisição.
Verifique se NO_PROXY não está fazendo correspondência acidental com algum hostname.
Se estiver usando um agent explícito, confirme que proxy: false está definido para o Axios não tentar tratar isso duas vezes.

Quando vale pular completamente a montagem manual de proxy

Tudo o que foi mostrado acima é realmente útil se o seu objetivo é roteamento de tráfego arbitrário — testes em rede corporativa, testes geográficos de um app ou saída controlada de rede. Mas muitos desenvolvedores chegam a “como configurar um proxy no Axios” porque, na verdade, o que querem são dados de um site, e o proxy é só um meio para isso.

Se esse for o seu caso, vale perguntar se você realmente precisa de um proxy ou se precisa de uma API de scraping que cuide da infraestrutura para você. A Open API do Thunderbit recebe uma URL e um schema e devolve JSON estruturado — sem parsing de HTML bruto, sem bibliotecas de agents, sem pool de proxies para manter. O endpoint /extract lida com páginas renderizadas em JS, mecanismos anti-bot e CAPTCHAs no servidor, e há também um endpoint mais leve, /distill, que só converte uma página em Markdown limpo, se isso for tudo o que você precisa. Existe ainda um servidor MCP expondo ferramentas como thunderbit_extract e thunderbit_suggest_fields, para que assistentes de código como Claude ou Cursor consigam puxar dados estruturados durante a tarefa sem encostar em configuração de proxy alguma, além de uma CLI para fluxos de terminal e CI.

Preocupação	DIY com Axios + Proxies	Thunderbit API/MCP/CLI
Obtenção e rotação de proxies	Você gerencia	Tratado no servidor
Desafios de navegador e acesso	Você opera a camada de navegador/rede	Gerenciado pelo serviço dentro das capacidades documentadas
Páginas renderizadas em JS	Precisa de browser headless	`renderMode: full`
Formato de saída	HTML bruto → você faz o parsing	JSON estruturado via schema
Manutenção quando os sites mudam	Você mantém parsers/selectors	A camada gerenciada de extração reduz parte da manutenção do lado da aplicação

A leitura honesta é a seguinte: se você precisa rotear tráfego para testes ou networking corporativo, nada disso substitui o Axios e uma configuração de proxy. Se o seu entregável é dado estruturado da web, uma abordagem API-first pode reduzir o código de proxy, navegador e parsing que sua aplicação precisa sustentar. No momento da coleta, em 7 de agosto de 2026, a documentação de rate limit da API do Thunderbit indicava o plano Free com 10 requisições por minuto e 2 requisições simultâneas. Trate isso como limite de API sujeito a mudanças e confira a página novamente antes de depender dele em produção.

Conclusão

A lição principal aqui vai contra o que muitos tutoriais antigos afirmam: o Axios atual documenta e, no teste local registrado, usou corretamente o tunneling CONNECT para um destino HTTPS. Falhas históricas continuam relevantes, mas precisam de contexto de versão e configuração. A configuração nativa é um bom ponto de partida de baixa complexidade; quando você precisa de controle por requisição, suporte a SOCKS ou rotação, um HttpsProxyAgent explícito (ou SocksProxyAgent) combinado com proxy: false oferece uma responsabilidade muito mais clara. E se você estiver rotacionando em produção com um pool, interceptors de requisição e resposta dão um ponto central e testável para fazer isso — só garanta que a lógica de retry tenha proteção contra loop e só repita requisições que realmente podem ser repetidas com segurança.

Salve a tabela de diagnóstico acima para a próxima vez que uma configuração de proxy jogar um erro enigmático na sua tela às 2h da manhã. E, se você perceber que está gastando mais tempo depurando a infraestrutura do proxy do que usando os dados que queria obter, talvez valha conferir se uma ferramenta de extração API-first resolve o problema real mais rápido do que a infraestrutura jamais resolveria.

Perguntas frequentes

O Axios oferece suporte nativo a proxies HTTPS? Sim, no Axios atual, para um proxy HTTP convencional: a documentação atual descreve tunneling CONNECT para alvos HTTPS, e o Axios 1.19.0 passou nesse caminho no teste local registrado. Versões históricas e configurações específicas de proxy produziram falhas reais, então verifique a versão exata e o proxy em uso, em vez de assumir sucesso ou fracasso universal.

Como faço rotação de proxies no Axios? Use um interceptor de requisição para atribuir um httpsAgent diferente de um pool de proxies antes de cada requisição sair, e combine isso com um interceptor de resposta que tente novamente as falhas usando outro proxy. Mantenha a lógica de retry limitada — uma tentativa de retry, e apenas para métodos idempotentes como GET — para não repetir acidentalmente uma requisição que não deveria ser repetida.

Por que meu proxy no Axios mostra meu IP real? Verifique se NO_PROXY, proxy:false, um agent direto explícito ou o roteamento específico do ambiente não estão ignorando o proxy. Registre as versões de Axios/Node e teste o proxy separadamente com cURL. Se você precisa de roteamento por requisição sem ambiguidades, use HttpsProxyAgent com proxy:false e valide o IP observado em um endpoint controlado.

Posso usar proxies SOCKS5 com Axios? Sim, por meio do pacote socks-proxy-agent. Crie uma instância de SocksProxyAgent com a URL SOCKS e passe-a como httpsAgent na configuração do Axios — só não passe também HttpsProxyAgent, já que os dois protocolos usam tipos de agent diferentes.

Qual é a diferença entre a opção proxy e httpsAgent no Axios? A opção proxy é a configuração nativa do Axios para um único proxy estático e funciona bem para casos diretos nas versões atuais. httpsAgent aceita um agent personalizado do Node.js — como HttpsProxyAgent ou SocksProxyAgent — dando a você controle direto, por requisição, sobre roteamento, autenticação e rotação, algo que a opção nativa nunca foi projetada para tratar.

Saiba mais

Extraia Dados usando IA

Transfira facilmente dados para Google Sheets, Airtable ou Notion

Chrome Store Rating

PRODUCT HUNT#1 Product of the Week