Cómo configurar Axios Proxy en Node.js: Auth, Rotación, SOCKS5

La forma más rápida de conseguir un proxy HTTP de Axios que funcione es pasar un proxy objeto directamente en una solicitud GET. Esto es lo mínimo imprescindible que necesitas:

const axios = require('axios');

axios.get('https://httpbin.org/ip', {
  proxy: { host: '123.45.67.89', port: 8080 }
}).then(res => console.log(res.data));

Ejecuta node app.js y comprueba el campo origin . Si muestra la IP del proxy en lugar de la dirección real de tu máquina, la configuración funciona. Esa única proxy clave es lo que distingue una solicitud directa de una que pasa por el proxy, y todo lo demás en esta guía sobre cómo configurar conexiones de proxy de Axios se basa en ella.

El proxy campo en una configuración de solicitud de Axios admite varias propiedades: host (cadena, obligatorio), port (número, obligatorio), protocol (por defecto http) y un auth subobjeto opcional que trataremos en la siguiente sección. A diferencia de las bibliotecas que analizan una cadena de URL de proxy, Axios mantiene estos como campos discretos, lo que hace que la configuración programática del proxy de Axios sea sencilla.

Hay dos formas de configurar un proxy en proyectos de Axios para Node.js: en línea en cada llamada, o integrado en una instancia reutilizable mediante axios.create().

Un proxy a nivel de instancia sigue permitiendo anulaciones por solicitud. Si pasas proxy la configuración de una llamada individual, esta tiene prioridad sobre el valor predeterminado de la instancia. Para desactivar el proxy para una llamada específica en una instancia que tenga uno, pasa proxy: false explícitamente. Esta flexibilidad por solicitud es una de las razones por las que merece la pena aprender a configurar los patrones de proxy de Axios.

La mayoría de los proxies comerciales requieren credenciales. Axios gestiona esto a través de un auth objeto anidado dentro de proxy, lo que simplifica la autenticación del proxy de Axios:

const axios = require('axios');

const client = axios.create({
  proxy: {
    host: process.env.PROXY_HOST,
    port: Number(process.env.PROXY_PORT),
    auth: {
      username: process.env.PROXY_USER,
      password: process.env.PROXY_PASS
    }
  }
});

client.get('https://httpbin.org/ip')
  .then(res => console.log(res.data))
  .catch(err => console.error(err.message));

Algunas notas prácticas:

• Guarda las credenciales en variables de entorno, no en el código fuente. Un .env archivo cargado con dotenv funciona bien durante el desarrollo.
• Los caracteres especiales en las contraseñas (como @, #, o %) son seguros dentro del auth objeto porque Axios no los codifica en URL como lo haría una cadena de URL de proxy. Esta es una de las ventajas del enfoque de configuración estructurada.
• Si tu proxy rechaza las credenciales, recibirás un estado 407 Proxy Authentication Required. Comprueba dos veces el nombre de usuario y la contraseña, y confirma que tu proveedor de proxy no haya caducado las credenciales.

Cuando tu URL de destino es HTTPS, Axios no reenvía la solicitud a través del proxy en texto sin formato. En su lugar, envía una solicitud HTTP CONNECT al proxy, pidiéndole que abra un túnel TCP sin procesar hacia el destino. Una vez establecido el túnel, el protocolo de enlace TLS se produce de extremo a extremo entre tu proceso Node.js y el servidor de destino. El proxy retransmite los bytes cifrados sin poder leerlos ni modificarlos.

Esto es importante por dos razones. En primer lugar, los datos extraídos se mantienen confidenciales incluso si el proxy es gestionado por un tercero. En segundo lugar, el sitio de destino ve una conexión TLS legítima, por lo que tus solicitudes parecen más naturales en comparación con el HTTP simple. Axios gestiona este túnel automáticamente cuando configuras un proxy para una URL de destino HTTPS (consulta la documentación de Node.js sobre HTTPS), por lo que no hay código adicional por tu parte. Solo ten en cuenta que el propio proxy solo necesita ser compatible con el método CONNECT, algo que prácticamente todos los proxies HTTP modernos hacen.

Una única IP de proxy será marcada rápidamente si envías cientos de solicitudes al mismo sitio. La rotación de proxies distribuye tu tráfico entre varias IP, de modo que el sitio de destino ve lo que parece ser muchos visitantes diferentes. Crear un grupo de proxies en proyectos de Axios Node.js requiere una clase de grupo y cierto manejo de proxies inactivos.

Aquí tienes un grupo round-robin mínimo que realiza un seguimiento de los proxies fallidos:

class ProxyPool {
  constructor(proxies) {
    this.proxies = proxies.map(p => ({ ...p, alive: true }));
    this.index = 0;
  }

  next() {
    const alive = this.proxies.filter(p => p.alive);
    if (!alive.length) throw new Error('All proxies dead');
    const proxy = alive[this.index % alive.length];
    this.index++;
    return { host: proxy.host, port: proxy.port, auth: proxy.auth };
  }

  markDead(host, port) {
    const p = this.proxies.find(
      px => px.host === host && px.port === port
    );
    if (p) p.alive = false;
  }
}

Utiliza el grupo con Axios de esta manera:

const pool = new ProxyPool([
  { host: '1.2.3.4', port: 8080, auth: { username: 'u1', password: 'p1' } },
  { host: '5.6.7.8', port: 8080, auth: { username: 'u2', password: 'p2' } },
  { host: '9.10.11.12', port: 3128 }
]);

async function fetchWithRotation(url) {
  const proxy = pool.next();
  try {
    const res = await axios.get(url, { proxy, timeout: 10000 });
    return res.data;
  } catch (err) {
    pool.markDead(proxy.host, proxy.port);
    return fetchWithRotation(url); // retry with next proxy
  }
}

Establecer un timeout (en milisegundos) es fundamental. Algunos proxies se cuelgan indefinidamente en lugar de devolver un error, y sin un tiempo de espera tu script se bloqueará. Diez segundos es un punto de partida razonable para la mayoría de las tareas de scraping. Si quieres saber más sobre cómo evitar bloqueos durante el scraping, vale la pena revisar los consejos para prevenir bloqueos de IP.

La lógica de rotación anterior reside en la función de llamada. Un patrón más limpio utiliza los interceptores de respuesta de Axios para cambiar automáticamente de proxy cuando el destino devuelve un 403 o un 429, eliminando el código de reintento manual de cada punto de llamada:

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

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

client.interceptors.response.use(
  response => response,
  async error => {
    const { config } = error;
    const status = error.response?.status;
    if ((status === 403 || status === 429) && !config._retried) {
      config._retried = true;
      pool.markDead(config.proxy.host, config.proxy.port);
      config.proxy = pool.next();
      return client.request(config);
    }
    return Promise.reject(error);
  }
);

El interceptor de solicitud asigna un proxy nuevo antes de cada llamada saliente. El interceptor de respuesta detecta las señales de bloqueo y vuelve a intentar la conexión con una IP diferente una vez por solicitud (el indicador _retried indicador evita bucles infinitos). Este enfoque basado en interceptores es un potente ejemplo de proxy de Axios para sistemas de producción, y permite cambiar la estrategia de rotación sin tocar ningún punto de llamada.

La opción integrada de Axios proxy solo admite proxies HTTP y HTTPS. Si necesitas un proxy SOCKS5 con Axios (que opera en una capa de red inferior y admite tanto UDP como TCP), necesitas el socks-proxy-agent paquete.

Instálalo junto con Axios:

npm install axios socks-proxy-agent

A continuación, crea un agente y pásalo a través de httpAgent y httpsAgent:

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

const agent = new SocksProxyAgent('socks5://user:pass@127.0.0.1:1080');

axios.get('https://httpbin.org/ip', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false  // disable built-in proxy so the agent handles routing
})
.then(res => console.log('SOCKS5 IP:', res.data.origin))
.catch(err => console.error(err.message));

Fíjate en la proxy: false en la línea 8. Esto es esencial al configurar un proxy SOCKS5 con Axios. Si dejas el proxy integrado habilitado junto con un agente personalizado, entrarán en conflicto. Establecer proxy: false le indica a Axios que transfiera todo el enrutamiento de la conexión a tu agente SOCKS.

Un error común al aprender a configurar conexiones de proxy con Axios: Axios no lee automáticamente HTTP_PROXY ni HTTPS_PROXY las variables de entorno como lo hacen herramientas como curl . Si configuras esas variables y esperas que Axios las detecte, no pasará nada. Tienes que leerlas tú mismo e introducirlas en la configuración:

const proxy = process.env.HTTP_PROXY
  ? { host: new URL(process.env.HTTP_PROXY).hostname,
      port: Number(new URL(process.env.HTTP_PROXY).port) }
  : undefined;

const res = await axios.get('https://example.com', { proxy });

Para desactivar el proxy de forma selectiva para determinadas solicitudes (por ejemplo, llamadas a API internas que no deben salir de tu red), pasa proxy: false en esas solicitudes individuales. Esto resulta útil cuando tienes un proxy a nivel de instancia configurado mediante axios.create() pero necesitas omitirlo para comprobaciones de estado, llamadas a localhost o solicitudes a API públicas para desarrolladores, donde un proxy solo añade latencia sin aportar ningún beneficio.

Cambiar las direcciones IP te permite superar los límites de velocidad más simples, pero los sofisticados sistemas antibots analizan mucho más que tu IP de origen. Según estudios del sector, las plataformas modernas de detección de bots analizan los patrones de sincronización de las solicitudes, las huellas TLS, la coherencia de los encabezados y señales de comportamiento como los movimientos del ratón o la profundidad de desplazamiento. La simple rotación a través de una lista de IP de centros de datos no engañará a estos sistemas.

Si ya has aprendido a configurar la rotación de proxies en Axios y sigues siendo bloqueado, considera estas capas adicionales:

• Encabezados HTTP realistas: alterna User-Agent cadenas e incluye encabezados como Accept-Language y Referer que enviaría un navegador real. El uso estratégico de los encabezados de Axios ayuda a evitar la detección.
• Diversidad de huellas TLS: Node.js genera una huella TLS distintiva. Las herramientas que emulan el comportamiento TLS de los navegadores pueden reducir tu superficie de detección.
• Redes de proxies residenciales: estas redirigen el tráfico a través de direcciones IP domésticas reales, lo que hace que las solicitudes sean prácticamente indistinguibles del tráfico de un usuario normal. Son más caras que los proxies de centros de datos, pero son mucho más eficaces contra la detección agresiva.

Incluso una configuración correcta del proxy de Axios puede fallar en tiempo de ejecución. Estos son los errores que encontrarás con más frecuencia y qué hacer al respecto:

• ECONNREFUSED: Axios no puede conectarse al proxy en absoluto. Comprueba el host y port , confirma que el servidor proxy está en funcionamiento y comprueba que ningún cortafuegos esté bloqueando la conexión.
• 407 Se requiere autenticación de proxy: el proxy ha rechazado tus credenciales. Confirma tu auth.username y auth.password son correctas y comprueba si tu proveedor ha rotado o caducado las credenciales.
• Tiempos de espera y solicitudes bloqueadas: algunos proxies aceptan la conexión pero nunca responden. Establece siempre un timeout en tu configuración de Axios para que tu script falle rápidamente. Comprender en profundidad los errores de estado del proxy puede ahorrarte horas de depuración.
• Conflictos de VPN: Ejecutar una VPN mientras se enruta a través de un proxy puede provocar un comportamiento inesperado, como que el tráfico siga una ruta incorrecta o que las conexiones fallen por completo. Añadir un proxy sobre una VPN suele ser redundante, a menos que necesites específicamente rotación de IP en una zona geográfica diferente.
• X-Forwarded-For Filtración de tu IP real: algunos proxies añaden tu IP original a este encabezado. Los proxies de élite o de alto nivel de anonimato la eliminan, así que comprueba el nivel de anonimato de tu proxy si la ocultación de la IP es importante.

• La forma más sencilla de configurar un proxy de Axios es pasar un proxy objeto con host y port en cualquier configuración de solicitud. La autenticación añade un auth subobjeto con username y password.
• Utiliza axios.create() para un proxy de toda la sesión, y anular con proxy o proxy: false cuando necesites flexibilidad.
• Para el scraping en producción, crea un grupo de proxies e intégralo en los interceptores de Axios para que la lógica de reintentos se mantenga fuera de tu código de negocio.
• Los proxies SOCKS5 requieren socks-proxy-agent pasado a través de httpAgent/httpsAgent, con el proxy configurado en false.
• Establece siempre un timeout en las solicitudes proxy. Los proxies bloqueados paralizarán silenciosamente todo tu proceso.

No. El proxy solo admite proxies HTTP y HTTPS. Para SOCKS5, instala el socks-proxy-agent paquete y pasa el agente resultante a httpAgent y httpsAgent en la configuración de la solicitud. Establece proxy: false para evitar conflictos con el gestor de proxy integrado.

Pasa proxy: false en la configuración de la solicitud para esa llamada específica. Esto anula cualquier proxy a nivel de instancia establecido mediante axios.create(). Es útil para solicitudes a servicios internos o puntos finales de localhost que no deben enrutarse a través del proxy.

Axios no lee automáticamente HTTP_PROXY ni HTTPS_PROXY . Debes analizarlas tú mismo en Node.js utilizando new URL(process.env.HTTP_PROXY) e inyectar el host y el puerto resultantes en la proxy config manualmente.

Los proxies de centro de datos utilizan direcciones IP de proveedores de servicios en la nube. Son rápidos, asequibles y están disponibles a gran escala, pero sus rangos de IP son bien conocidos y más fáciles de bloquear por los sitios web. Los proxies residenciales utilizan direcciones IP asignadas por los proveedores de servicios de Internet a hogares reales, lo que los hace más difíciles de detectar, pero también más caros y más lentos.

Envía una solicitud GET a https://httpbin.org/ip a través de tu proxy configurado. Compara el origin campo de la respuesta con la dirección IP real de tu equipo. Si difieren, el proxy está activo. Para una verificación más exhaustiva, comprueba https://httpbin.org/headers para confirmar que los encabezados de la solicitud coinciden con lo esperado.

Saber cómo configurar correctamente las conexiones de proxy de Axios empieza siendo sencillo (tres campos de configuración), pero se vuelve más complejo una vez que se tienen en cuenta la autenticación, el túnel HTTPS, la lógica de rotación, la compatibilidad con SOCKS5 y la gestión de errores. Los patrones de esta guía abarcan todo, desde experimentos rápidos hasta procesos de scraping listos para producción.

La conclusión más importante: la configuración del proxy es solo la mitad del camino. También necesitas proxies fiables, tiempos de espera razonables y una lógica de reintentos que no sature un punto final inactivo. Si dominas estos fundamentos, tu scraper basado en Axios será mucho más resistente.

Si la gestión de grupos de proxies, la rotación y la evasión de bots te está consumiendo más tiempo de ingeniería que la propia extracción de datos, WebScrapingAPI se encarga de la rotación de proxies, la resolución de CAPTCHA y la lógica de reintentos detrás de un único punto de acceso, lo que te permite mantener tu código Axios y centrarte en lo que haces con los datos.