Configuração de proxy no Node.js: axios, got, fetch e undici (Guia 2026)

Cada cliente HTTP do Node.js lida com proxies de forma diferente, e metade deles não lida com a autenticação de proxy de jeito nenhum sem um pacote auxiliar. O axios ignora silenciosamente sua própria opção proxy para alvos HTTPS em algumas versões, o fetch nativo não tem absolutamente nenhuma opção de proxy, e as mensagens de erro — ECONNRESET, 407, ou simplesmente um travamento — não te dizem nada.

Esta é a referência completa e funcional para rotear axios, got, node-fetch, fetch nativo (undici) e superagent através de proxies residenciais autenticados. É o complemento Node dos nossos guias Python (requests/httpx/aiohttp, Scrapy). Todos os exemplos usam o formato de placeholder padrão — troque pelas suas credenciais reais:

socks5h://USERNAME:[email protected]:913

A Única Regra Que Previne a Maioria dos Bugs

Não use as opções proxy embutidas. Use um proxy agent. Os clientes HTTP do Node delegam o gerenciamento de conexão a um objeto "agent", e os pacotes de agent (https-proxy-agent, socks-proxy-agent) implementam o tunelamento CONNECT e a autenticação corretamente. As opções embutidas frequentemente não fazem isso — a configuração proxy do axios é o exemplo mais notório.

npm install socks-proxy-agent https-proxy-agent

axios

const axios = require("axios");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await axios.get("https://api.ipify.org?format=json", {
  httpAgent: agent,    // for http:// targets
  httpsAgent: agent,   // for https:// targets
  proxy: false,        // IMPORTANT: disable axios's own proxy handling
});
console.log(res.data); // -> the proxy's exit IP

Duas coisas que as pessoas esquecem: você precisa definir ambos httpAgent e httpsAgent (o axios escolhe pelo esquema do alvo), e você precisa definir proxy: false para que o axios não tente também aplicar as variáveis de ambiente HTTP_PROXY por cima do seu agent.

got

const got = require("got");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const body = await got("https://api.ipify.org?format=json", {
  agent: { http: agent, https: agent },
}).json();

Se você está fazendo scraping de alvos protegidos com got, dê uma olhada em got-scraping — mesma API, mais geração de headers parecidos com os de um navegador e mimetização de fingerprint HTTP/2 (por que isso importa: JA3/JA4 explicados).

fetch nativo / undici (Node 18+)

O fetch embutido do Node vem do undici, ignora as variáveis de ambiente de proxy e não tem opção agent. O jeito undici é um dispatcher:

const { ProxyAgent } = require("undici");

// undici's ProxyAgent speaks HTTP CONNECT (use your HTTP proxy port)
const dispatcher = new ProxyAgent({
  uri: "http://us.jibaoproxy.com:1000",
  token: "Basic " + Buffer.from("USERNAME:PASSWORD").toString("base64"),
});

const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());

Nota: o ProxyAgent do undici é apenas para proxy HTTP. Para SOCKS5 com fetch nativo, coloque um forwarder local na frente ou use um cliente que aceite socks agents (axios/got acima).

node-fetch (v2/v3)

const fetch = require("node-fetch");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await fetch("https://api.ipify.org?format=json", { agent });

Rotação: Nova Identidade por Requisição vs Sessões Sticky

Com um gateway residencial rotativo você não gerencia listas de IP — o gateway te entrega uma saída nova a cada conexão, ou mantém uma saída por session id. No Node isso mapeia de forma limpa para um agent por identidade:

// Sticky: same session id -> same exit IP across requests
function identityAgent(sessionId) {
  return new SocksProxyAgent(
    `socks5h://USERNAME-session-${sessionId}:[email protected]:913`
  );
}

// Account A keeps IP A, account B keeps IP B - cookies and IP move together
const agentA = identityAgent("acct_a");
const agentB = identityAgent("acct_b");

Reutilize o agent para pooling de conexões dentro de uma identidade; nunca compartilhe um agent entre identidades. Quando rotacionar vs manter fixo é um tópico próprio — veja sessões sticky vs rotativas.

Tabela de Resolução de Problemas

Sintoma	Causa	Correção
407 Proxy Authentication Required	Credenciais não chegam ao proxy	Coloque user:pass na URL do agent, não na config do cliente
axios funciona em http://, falha em https://	Apenas httpAgent definido	Defina httpsAgent também, e proxy: false
ECONNRESET imediato	Porta errada / protocolo errado (porta HTTP com agent SOCKS)	Combine o tipo de agent com a porta
Vazamentos de DNS / hostnames internos falham	socks5:// resolve DNS localmente	Use socks5h:// — o h envia os hostnames através do proxy
fetch nativo ignora HTTP_PROXY	undici não lê variáveis de ambiente	Passe um dispatcher explicitamente
Funciona localmente, 403 no site alvo	Não é bug de proxy — fingerprint TLS	got-scraping ou um navegador real; veja o guia de TLS

Resumo

• Sempre use os pacotes de agent (socks-proxy-agent / https-proxy-agent); nunca confie nas opções de proxy embutidas.
• axios: ambos os agents + proxy: false. got: agent: {http, https}. fetch nativo: dispatcher ProxyAgent do undici.
• Use socks5h:// para que o DNS resolva através do proxy — sem vazamentos.
• Um agent por identidade: session ids sticky mantêm os cookies e o IP de saída se movendo juntos.
• Ainda bloqueado com um proxy funcionando? Isso é fingerprinting, não o proxy — mude para got-scraping ou um navegador.