La configuración del proxy de Axios es una característica de Node.js. Axios del lado del navegador no puede elegir un proxy saliente porque el navegador controla la pila de red.
Axios 1.19.0 acepta un objeto proxy con protocol, host, port y auth opcional. Establece un tiempo de espera y valida el contenido devuelto, no solo el estado.
Las variables de entorno convencionales HTTP_PROXY, HTTPS_PROXY y NO_PROXY funcionan en Node.js. Establece proxy: false cuando un Agent personalizado debe ser el único mecanismo de enrutamiento.
Los clientes de ronda rotativa hacen que la selección del proxy sea observable. Agrega la salud del endpoint, tiempos de enfriamiento y un presupuesto de reintentos finito antes de aumentar el volumen.
Usa un Agent para protocolos o políticas de túneles fuera de la ruta de proxy HTTP incorporada de Axios. Empareja HttpProxyAgent, HttpsProxyAgent o SocksProxyAgent con el endpoint real.
¿Qué es un proxy de Axios?
Un proxy de Axios es un intermediario configurado para el adaptador de Node.js de Axios, de modo que las solicitudes viajen a través de un endpoint de red designado. La configuración de solicitud oficial de Axios define una opción solo para Node.js con el protocolo de proxy, nombre del host, puerto y credenciales de autenticación básica opcionales.
Axios aún maneja la configuración de la solicitud, promesas, análisis de respuestas, tiempos de espera, comportamiento de redirección y errores. El proxy cambia la ruta entre el proceso de Node.js y el destino. Un endpoint estándar como Nstdata Residential Prime Proxies puede conectarse a través del objeto proxy normal de Axios sin un paquete JavaScript específico del proveedor.
El límite del navegador es importante. Axios que se ejecuta en una página web utiliza un adaptador de navegador, y JavaScript no puede seleccionar un proxy saliente del sistema o por solicitud. Configura el navegador, el sistema operativo, la extensión, el corredor de pruebas o el proxy inverso en su lugar. Un campo proxy en un servidor de desarrollo de React también es una característica de la herramienta de construcción, no la configuración de solicitud de Axios que se describe aquí.
Usa proxies de Axios para verificaciones de API autorizadas, control de calidad de localización, monitoreo de precios, flujos de datos públicos y salida controlada del servidor. Un proxy no otorga permiso al objetivo ni garantiza que una respuesta exitosa contenga los datos previstos.
Cómo funciona el enrutamiento del proxy de Axios en Node.js
El enrutamiento del proxy de Axios tiene tres puntos de control: un objeto proxy explícito, variables de entorno convencionales o un Agent personalizado. Elige un mecanismo dominante por solicitud para que la ruta siga siendo comprobable.
Mecanismo
Mejor ajuste
Límite importante
proxy: { protocol, host, port }
Configuración estándar de proxy HTTP o HTTPS
Solo adaptador de Node.js
HTTP_PROXY / HTTPS_PROXY
Enrutamiento gestionado por implementación
NO_PROXY puede omitir hosts seleccionados
httpAgent / httpsAgent
Túneles personalizados, política de conexión o SOCKS
Establece proxy: false para evitar manejo doble
La documentación actual de Axios declara que una puerta de enlace HTTP puede establecer túneles CONNECT para destinos HTTPS y que las credenciales del proxy se envían en el intercambio de proxy. Mantén habilitada la verificación TLS de origen. Si una ruta de inspección legítima utiliza un CA privado, instala el CA aprobado en lugar de deshabilitar las comprobaciones de certificados.
La lista oficial de lanzamientos de Axios enumera la versión v1.19.0 como la última versión en el momento de la prueba. Este artículo fija esa versión porque las versiones recientes cambiaron el comportamiento del proxy, redirección, redacción de errores y adaptador de Node.js.
Requisitos previos
Los ejemplos se ejecutaron con Node.js 22.23.2, Axios 1.19.0 y http-proxy-agent 7.0.2. Crea un proyecto ESM e instala los paquetes probados:
Agrega "type": "module" a package.json, luego proporciona una TARGET_URL autorizada y la configuración del proxy a través de variables de entorno protegidas. Nunca cometas contraseñas de proxy ni registres el endpoint completo.
Establece tiempos de espera limitados y límites de tamaño de respuesta según tu aplicación. La documentación actual de configuración de solicitudes advierte que los tamaños máximos de respuesta y cuerpo no tienen límites por defecto, por lo que los servicios que llaman a servidores no confiables deben establecer límites explícitos.
Puedes usar Axios con proxies a través de cinco métodos probados de Node.js: el objeto proxy nativo, autenticación de proxy, variables de entorno, un grupo de rotación reutilizable o un Agente personalizado. Cada ejemplo a continuación se ejecutó contra un endpoint local construido específicamente que devolvió su ID de ruta no secreta y URL objetivo.
Método 1: Configura Un Proxy en una Instancia de Axios
Usa axios.create() cuando múltiples llamadas compartan un proxy, tiempo de espera y política de respuesta. Una instancia mantiene la configuración de enrutamiento separada de llamadas de Axios no relacionadas.
La respuesta ejecutada contenía ruta: basic-18580 y la URL objetivo absoluta http://fixture.test/items. En producción, reemplaza el marcador fijo con una respuesta de reflexión IP autorizada o un identificador de sesión de proveedor.
Siempre convierte el puerto a un número y nombra el protocolo de forma explícita. Una cadena copiada como host no debe contener http://; protocolo, host y puerto son campos separados. La guía de proxy de Node.js de Nstdata cubre la misma capa de enrutamiento más allá de Axios.
Método 2: Usa un Proxy de Axios Autenticado
Usa proxy.auth cuando un proxy HTTP requiera autenticación Basic. Pasar nombre de usuario y contraseña como campos separados evita construir manualmente una URL que contenga credenciales.
importaxiosfrom"axios";const response =await axios.get(process.env.TARGET_URL,{proxy:{protocol:"http",host: process.env.PROXY_HOST,port:Number(process.env.PROXY_PORT),auth:{username: process.env.PROXY_USERNAME,password: process.env.PROXY_PASSWORD,},},timeout:10_000,});if(response.data.route!=="auth-18581"||!response.data.authenticated){thrownewError(`Falló la autenticación del proxy: ${JSON.stringify(response.data)}`);}console.log({route: response.data.route,authenticated: response.data.authenticated});
El proxy local primero requirió un desafío 407 y luego aceptó un nombre de usuario que contenía un espacio y una contraseña que contenía @ y :. Axios devolvió { route: 'auth-18581', authenticated: true }.
La configuración `proxy.auth` de Axios sobrescribe un encabezado `Proxy-Authorization` proporcionado manualmente. Mantén las credenciales del proxy distintas de las credenciales del servidor de destino: la `auth` de la solicitud o un encabezado `Authorization` autentican al destino, mientras que `proxy.auth` autentica al intermediario.
### Método 3: Usar HTTP_PROXY y HTTPS_PROXY
Utiliza variables de entorno de proxy cuando la plataforma de ejecución posee el enrutamiento saliente. Axios resuelve las variables de proxy convencionales en Node.js, y `NO_PROXY` proporciona hosts que deben ir directamente.
```bash
export HTTP_PROXY="http://proxy.example:9000"
export HTTPS_PROXY="http://proxy.example:9000"
export NO_PROXY="localhost,127.0.0.1"
node app.mjs
La ejecución basada en el entorno imprimió basic-18580 sin un objeto proxy explícito. Inspecciona las variables en mayúsculas y minúsculas, NO_PROXY, configuraciones de contenedores y configuración del gestor de servicios cuando el comportamiento difiere entre máquinas.
Establece proxy: false en una solicitud o instancia cuando Axios deba ignorar las variables de entorno de proxy. Esto es esencial cuando un Agente personalizado ya realiza el enrutamiento del proxy.
Método 4: Rotar un Pool de Clientes Axios Limitados
Utiliza instancias de Axios preconfiguradas para una rotación determinista del lado de la aplicación. La selección round-robin asegura que cada punto final disponible reciba trabajo en un orden conocido.
importaxiosfrom"axios";const proxyConfigs =[{protocol:"http",host:"127.0.0.1",port:18580},{protocol:"http",host:"127.0.0.1",port:18582},];const clients = proxyConfigs.map((proxy)=> axios.create({ proxy,timeout:10_000}));const routes =[];for(let index =0; index <4; index +=1){const response =await clients[index % clients.length].get(process.env.TARGET_URL);if(typeof response.data.route!=="string"){thrownewError("La respuesta no contenía un marcador de ruta");} routes.push(response.data.route);}console.log(routes);
La salida alternó entre basic-18580, rotate-18582, basic-18580 y rotate-18582. La elección aleatoria puede seleccionar repetidamente el mismo punto final; la selección determinista es más fácil de observar y probar. La guía de rotación de IP para web scraping explica cómo los cambios de ruta afectan a trabajos de recopilación independientes.
La rotación en producción necesita más que selección. Haz un seguimiento de los fallos consecutivos, aplica enfriamientos, limita la concurrencia y vuelve a intentar solo errores transitorios. No reproduzcas automáticamente una solicitud que cambia el estado a menos que la operación sea idempotente o lleve una clave de idempotencia. Mantén las cookies y una ruta fija juntas para una sesión con estado.
Método 5: Enrutar Axios a Través de un Agente Personalizado
Utiliza un Agente personalizado cuando el protocolo del punto final o la política de túnel esté fuera de la ruta de proxy nativa de Axios. Desactiva la resolución de proxy de Axios para que el Agente sea la única fuente de verdad de enrutamiento.
La ejecución basada en el Agente imprimió basic-18580. El paquete http-proxy-agent está destinado a conexiones de proxy HTTP. Para un túnel HTTPS o un punto final SOCKS, utiliza el Agente correspondiente y asígnalo al campo httpAgent o httpsAgent correcto. Codifica las credenciales cuando estén incrustadas en una URL de Agente.
Cómo Verificar una Ruta de Proxy de Axios
Verifica una ruta de proxy de Axios comprobando la salida de red, el contrato de respuesta y los datos aceptados por separado. Comienza con un punto final de reflexión IP autorizado o un diagnóstico controlado. Confirma su identificador de ruta, luego llama al destino real y exige el tipo de contenido esperado, estado y campo semántico estable.
Axios normalmente rechaza respuestas fuera de su rango de estado aceptado, pero un estado 200 aún puede llevar una página de error, pantalla de inicio de sesión, localización alternativa o esquema JSON inesperado. La guía oficial de manejo de errores de Axios distingue errores con respuestas, errores sin respuestas y fallos de configuración. Registra solo códigos de error no secretos, IDs de ruta y tiempos.
Establecer un AbortSignal o un tiempo de espera, limitar el tamaño de la respuesta y restringir las redirecciones. Preservar los encabezados sensibles del servidor objetivo solo donde se pretenda; las versiones recientes de Axios incluyen endurecimiento de redirección y serialización, pero las aplicaciones aún necesitan una política de destino autorizada cuando las URL provienen de entradas externas.
Elegir una Ruta Nstdata para Axios
Los Proxies Residenciales Prime de Nstdata proporcionan puntos finales autenticados estándar para flujos de trabajo de Node.js que necesitan enrutamiento residencial, selección de ubicación y sesiones rotativas o fijas en la superficie del producto actual. Axios puede conectarse a través de su objeto proxy nativo o un Agente compatible, lo que mantiene la lógica de negocio independiente del SDK específico del proveedor. Los modelos de facturación de paquete y uso por demanda permiten a los equipos seleccionar un modelo operativo después de medir el tráfico y las respuestas aceptadas. El producto se adapta a la localización autorizada, monitoreo de precios, verificación de anuncios y trabajos de datos públicos; prueba el destino, el protocolo y la política de sesión antes de aumentar la concurrencia.
Configuración nativa de Axios: Mapea el punto final generado a protocol, host, port y proxy.auth.
Enrutamiento consciente de sesión: Utiliza rotación para llamadas independientes o mantén una ruta fija con trabajo dependiente de cookies.
La infraestructura de proxy no valida campos JSON ni renderiza aplicaciones solo para navegador. La guía de raspado web en JavaScript ayuda a determinar si un cliente HTTP es suficiente o si el flujo de trabajo requiere ejecución en navegador.
Errores Comunes de Proxy en Axios y Soluciones
Síntoma
Causa probable
Solución práctica
ECONNREFUSED
Host/puerto incorrecto o proxy fuera de línea
Confirma la accesibilidad y el protocolo; utiliza un tiempo de espera limitado.
407 Proxy Authentication Required
Credenciales de proxy faltantes o inválidas
Verifica los campos proxy.auth y la política de cuenta; no reintentes credenciales incorrectas indefinidamente.
El proxy funciona para HTTP pero falla en HTTPS
Problema de confianza CONNECT o TLS
Confirma el soporte de túnel y la CA prevista; nunca desactives la verificación TLS como solución permanente.
Se muestra IP directa
NO_PROXY coincidió o se está utilizando Axios del lado del navegador
Inspecciona las reglas de omisión del entorno; configura el enrutamiento del navegador fuera de Axios.
El Agente personalizado es ignorado o duplicado
La resolución de proxy de Axios aún está activa
Establece proxy: false y adjunta el Agente al campo correcto.
Fallo del endpoint SOCKS en proxy
La opción incorporada espera un proxy compatible con HTTP
Utiliza un Agente SOCKS mantenido y una URL SOCKS codificada.
Estado 200 pero datos inválidos
Error suave o respuesta alternativa
Valida el tipo de contenido, el marcador de ruta y el esquema específico del dominio.
Una configuración de proxy de Axios confiable comienza con el límite de Node.js y un mecanismo de enrutamiento explícito. Utiliza el objeto proxy nativo para gateways HTTP estándar, proxy.auth para credenciales, variables de entorno para rutas gestionadas por el despliegue y proxy: false con un Agente personalizado cuando el Agente posee el comportamiento de transporte.
Comienza con un objetivo autorizado y demuestra el contrato de ruta y respuesta. Agrega un grupo de clientes limitado solo después de que el tiempo de espera, la validación semántica y la clasificación de fallos estén funcionando; considera el Administrador de Proxy Nstdata más adelante si los grupos, la salud y las políticas de enrutamiento superan el código de la aplicación.
Experimenta Nstdata — Comienza tu Prueba Gratuita Hoy
Q: ¿Funciona la configuración de proxy de Axios en un navegador?
No. La opción proxy de Axios es solo para Node.js; el JavaScript del navegador no puede seleccionar el proxy saliente del navegador. Configura el navegador, el sistema, la extensión, el servidor de desarrollo o la puerta de enlace ascendente en su lugar.
Q: ¿Cómo me autentico a un proxy en Axios?
Agrega auth: { username, password } dentro del objeto proxy de Axios. Mantén esos valores en una configuración de tiempo de ejecución protegida y distínguelos de la autorización del servidor objetivo.
Q: ¿Axios soporta HTTP_PROXY y HTTPS_PROXY?
Sí. Axios soporta variables de entorno de proxy convencionales en Node.js, mientras que NO_PROXY omite los hosts coincidentes. Usa proxy: false cuando la solicitud debe ignorarlos.
Q: ¿Puede Axios usar un proxy SOCKS5?
Axios requiere un agente compatible con SOCKS en lugar de su objeto proxy HTTP incorporado. Establece tanto el campo Agent apropiado como proxy: false para que Axios no aplique una segunda ruta.
P: ¿Cómo debería rotar los proxies con Axios?
Crea un conjunto limitado de instancias de Axios configuradas y selecciona las mismas con una política observable, como round-robin o elección consciente de salud. Agrega períodos de enfriamiento y un presupuesto de reintentos finito en lugar de reintentar cada fallo a través de cada punto final.
P: ¿Por qué un proxy de Axios devuelve estado 200 con el contenido incorrecto?
Un proxy o objetivo puede devolver una página de error suave con estado 200. Requiere el tipo de contenido esperado, evidencia de ruta y campos específicos del dominio antes de aceptar la respuesta.
Marcus Chen
Aug. 20th 2026
110M+ IP reales con 99.9% de acceso exitoso
Respuesta media ultrarrapida ~0.5s para tareas de alta concurrencia
Desde solo $0.1/GB
Acceso inmediato a pools premium de proxies residenciales, datacenter, IPv6 e ISP.
