Configuración de proxy en Node.js: axios, got, fetch y undici (Guía 2026)

Cada cliente HTTP de Node.js gestiona los proxies de forma distinta, y la mitad de ellos no gestionan en absoluto la autenticación de proxy sin un paquete auxiliar. axios ignora silenciosamente su propia opción proxy para destinos HTTPS en algunas versiones, el fetch nativo no tiene ninguna opción de proxy, y los mensajes de error — ECONNRESET, 407 o simplemente un cuelgue — no te dicen nada.

Esta es la referencia completa y funcional para enrutar axios, got, node-fetch, fetch nativo (undici) y superagent a través de proxies residenciales autenticados. Es el complemento para Node de nuestras guías de Python (requests/httpx/aiohttp, Scrapy). Todos los ejemplos usan el formato de marcador estándar — sustituye tus credenciales reales:

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

La única regla que evita la mayoría de los errores

No uses las opciones proxy integradas. Usa un agente de proxy. Los clientes HTTP de Node delegan la gestión de la conexión en un objeto "agent", y los paquetes de agentes (https-proxy-agent, socks-proxy-agent) implementan correctamente el tunelado CONNECT y la autenticación. Las opciones integradas a menudo no lo hacen — la configuración proxy de axios es el ejemplo más notorio.

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

Dos cosas que la gente pasa por alto: debes establecer ambos, httpAgent y httpsAgent (axios elige según el esquema del destino), y debes establecer proxy: false para que axios no intente además aplicar las variables de entorno HTTP_PROXY por encima de tu agente.

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();

Si estás haciendo scraping de destinos protegidos con got, mira got-scraping en su lugar — la misma API, además de generación de cabeceras similares a las de un navegador e imitación de la huella HTTP/2 (por qué importa: JA3/JA4 explicado).

fetch nativo / undici (Node 18+)

El fetch integrado de Node proviene de undici, ignora las variables de entorno de proxy y no tiene opción agent. La forma de undici es un 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: el ProxyAgent de undici es solo para proxy HTTP. Para SOCKS5 con fetch nativo, ponle delante un reenviador local o usa un cliente que acepte agentes socks (axios/got arriba).

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 });

Rotación: nueva identidad por petición vs. sesiones sticky

Con una puerta de enlace residencial rotativa no gestionas listas de IP — la puerta de enlace te entrega una salida nueva por conexión, o mantiene una salida por id de sesión. En Node eso se traduce limpiamente en un agente por identidad:

// 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");

Reutiliza el agente para el pooling de conexiones dentro de una identidad; nunca compartas un mismo agente entre identidades. Cuándo rotar vs. mantener fija (sticky) es un tema en sí mismo — consulta sesiones sticky vs. rotativas.

Tabla de resolución de problemas

Síntoma	Causa	Solución
407 Proxy Authentication Required	Las credenciales no llegan al proxy	Pon user:pass en la URL del agente, no en la configuración del cliente
axios funciona en http://, falla en https://	Solo está definido httpAgent	Define también httpsAgent y proxy: false
ECONNRESET de inmediato	Puerto incorrecto / protocolo incorrecto (puerto HTTP con agente SOCKS)	Haz coincidir el tipo de agente con el puerto
Fugas de DNS / fallan los nombres de host internos	socks5:// resuelve el DNS localmente	Usa socks5h:// — la h envía los nombres de host a través del proxy
fetch nativo ignora HTTP_PROXY	undici no lee variables de entorno	Pasa un dispatcher explícitamente
Funciona en local, 403 en el sitio destino	No es un error del proxy — es la huella TLS	got-scraping o un navegador real; consulta la guía de TLS

Resumen

• Usa siempre los paquetes de agentes (socks-proxy-agent / https-proxy-agent); nunca confíes en las opciones de proxy integradas.
• axios: ambos agentes + proxy: false. got: agent: {http, https}. fetch nativo: dispatcher ProxyAgent de undici.
• Usa socks5h:// para que el DNS se resuelva a través del proxy — sin fugas.
• Un agente por identidad: los ids de sesión sticky mantienen las cookies y la IP de salida moviéndose juntas.
• ¿Sigues bloqueado con un proxy que funciona? Eso es huella digital, no el proxy — cambia a got-scraping o a un navegador.