Configurar un proxy en Axios: enrutamiento, autenticación y NO_PROXY

Con Axios en Node.js, empieza por el adaptador HTTP y un objeto proxy explícito. Mantén las credenciales del proxy en proxy.auth, verifica la ruta y solo entonces añade variables de entorno o agentes personalizados. Esas capas pueden cambiar la conexión: en nuestra prueba local, proxy: false siguió usando un proxy cuando un agente personalizado de Node tenía configurado proxyEnv.

Esta guía usa Axios 1.20.0 y Node.js 24.20.0. Sus 15 casos de enrutamiento y sus cuatro comprobaciones de recetas son pruebas sintéticas en loopback, no mediciones de un servicio de proxies externo. Axios en el navegador y el adaptador fetch de Axios son rutas distintas; la opción proxy pertenece al adaptador HTTP de Node. Consulta la configuración de Axios y el adaptador HTTP en la versión fijada.

Ejecuta una comprobación explícita del proxy

Usa juntos proxy-check.mjs, package.json y el lockfile. En un directorio nuevo, con Node 24.20.0 o posterior dentro de la línea Node 24:

for file in package.json package-lock.json proxy-check.mjs; do
  curl --fail --silent --show-error \
    "https://ipvolt.com/downloads/axios-proxy-setup/$file" -o "$file" || exit 1
done
npm ci --ignore-scripts --no-audit --no-fund

Haz que tu gestor de secretos proporcione PROXY_HOST, PROXY_PORT, PROXY_USER y PROXY_PASSWORD y ejecuta después node proxy-check.mjs. PROXY_HOST es un nombre de host sin esquema ni credenciales. PROXY_PROTOCOL vale http por defecto; usa https solo con un endpoint de proxy TLS documentado por el proveedor. Describe la conexión con el proxy, no con el destino. No pongas contraseñas reales en el historial del shell ni en el prompt de un agente de programación.

El comprobador construye esta configuración con campos de credenciales separados:

const proxy = {
  protocol: process.env.PROXY_PROTOCOL || 'http',
  host: process.env.PROXY_HOST,
  port: Number(process.env.PROXY_PORT),
  auth: {
    username: process.env.PROXY_USER,
    password: process.env.PROXY_PASSWORD,
  },
};

Este fragmento muestra la forma; el script descargable valida sus entradas y realiza la petición. Selecciona adapter: 'http', desactiva las redirecciones, limita la respuesta a 4 KiB y tiene un tiempo de espera de Axios de 5 segundos más una señal de aborto de 6 segundos. Comprueba que el JSON devuelto contiene una dirección IP válida e imprime solo el resultado, el estado y una IP o un código de error. No imprime el error en bruto de Axios ni la configuración de la petición, que pueden contener credenciales.

Al ejecutar el script se envía por defecto una petición a través de tu proxy al endpoint JSON IPv4 de ipify, un servicio de terceros. Ese servicio observa la dirección pública de origen de la petición. Define en CHECK_URL una URL HTTPS sin credenciales de un endpoint aprobado que devuelva la misma forma { "ip": "..." }. Una IP observada es una sola comprobación de ruta; no verifica un país, un operador, una clasificación residencial ni una garantía de rendimiento. Probamos el comprobador con respuestas locales controladas, no con el ipify público.

Las credenciales Basic enviadas a un proxy HTTP corriente no viajan cifradas en la conexión del cliente al proxy solo porque el destino sea HTTPS. Usa un endpoint de proxy TLS cuando esté disponible y mantén activada la verificación de certificados. El laboratorio prueba un proxy HTTP que abre un túnel hacia un origen HTTPS de confianza; no prueba el transporte TLS hasta el propio proxy.

Elige qué capa controla el enrutamiento

Estas observaciones usan el fixture fijado, con los flags de arranque del proxy de entorno nativo desactivados. «Directo» significa que el proxy del fixture no recibió nada; «por proxy» significa que registró una petición o un CONNECT. Los resultados en bruto conservan esas observaciones.

En el enrutamiento por entorno, HTTP_PROXY se aplica a un destino HTTP y HTTPS_PROXY a un destino HTTPS. El esquema del valor sigue describiendo el proxy: HTTPS_PROXY=http://gateway:port puede seleccionar un proxy HTTP para un destino HTTPS. La guía de variables de entorno explica la herencia. La matriz de NO_PROXY existente cubre sus propios clientes y versiones, no este experimento con Axios.

La fila del agente nativo es la excepción a una lectura general de «false desactiva los proxies». El soporte de proxy integrado de Node puede dar a un agente su propia configuración de enrutamiento. En el fixture, proxy: false con ese agente siguió usando su proxy; al sustituirlo por un agente simple, la petición de control fue directa. No probamos todos los flags de arranque ni los agentes de terceros. Inspecciona el agente que recibe tu proceso en lugar de tratar un ajuste de Axios como una garantía para toda la red.

Para el fetch nativo de Node, usa la guía del dispatcher de Undici. Un objeto proxy de Axios y un dispatcher de fetch son interfaces distintas.

HTTPS y autenticación: encuentra la capa que falla

El adaptador HTTP de Axios 1.20.0 estableció un túnel CONNECT para el destino HTTPS del laboratorio. Una CA local de confianza permitió la petición; al retirar esa confianza se produjo DEPTH_ZERO_SELF_SIGNED_CERT. En el caso del certificado rechazado, el proxy vio el CONNECT, pero el origen HTTPS no recibió ninguna petición de la aplicación. El consejo de que Axios siempre necesita un paquete de túnel aparte no describe esta versión probada.

Usa proxy.auth para las credenciales del proxy; el auth de nivel superior de Axios es la autenticación del destino. En el caso de CONNECT correcto, el origen del fixture no recibió ninguna cabecera Proxy-Authorization. El proxy recibió esa credencial en el paso del túnel. Esto se limita a la configuración probada, no a proxies interceptores arbitrarios ni a redirecciones.

Las credenciales incorrectas produjeron el estado 407 y el código ERR_BAD_REQUEST tanto en el caso de HTTP simple como en el caso de HTTPS CONNECT del comprobador. El CONNECT rechazado llegó al proxy, pero no produjo ninguna petición al origen. Un error en bruto de Axios puede incluir su configuración con credenciales: conserva un código saneado y el estado disponible en lugar de registrar el objeto entero.

El origen HTTP bloqueado produjo ECONNABORTED con un tiempo de espera del fixture de 100 ms. Eso establece una rama de fallo local, no un tiempo de espera útil para producción ni una medición de latencia. El comprobador reutilizable usa plazos acotados más largos y nunca reintenta automáticamente.

Reproduce la matriz de enrutamiento

Descarga lab.mjs junto al comprobador y a los archivos de paquete fijados y ejecuta:

curl --fail --silent --show-error \
  https://ipvolt.com/downloads/axios-proxy-setup/lab.mjs -o lab.mjs
node lab.mjs local-results.json

El README documenta los requisitos previos y los casos. El fixture necesita OpenSSL, abre puertos IPv4 aleatorios en loopback, genera un certificado local temporal y usa credenciales inventadas. Quita antes los flags de arranque del proxy de entorno nativo; el banco de pruebas los rechaza porque alteran su punto de partida. La instalación de dependencias contacta con el registro de paquetes; las peticiones del fixture se quedan en loopback.

Registrado el 28 de septiembre de 2026 con Node 24.20.0, Axios 1.20.0 y macOS arm64: se superaron los 15 casos de enrutamiento y las cuatro comprobaciones de recetas. Las comprobaciones cubren enrutamiento, autenticación, HTTPS local de confianza y sin confianza, alcance del adaptador, tiempo de espera, salida de IP válida y rechazo de un cuerpo inesperado. No miden el inventario del proveedor, el anonimato, la geografía ni el rendimiento, y no prueban SOCKS, Axios en el navegador, redirecciones ni el transporte TLS hasta el proxy. Vuelve a ejecutar el fixture después de cambiar Axios, Node, un adaptador o un agente.

Si quieres ayuda de diagnóstico opcional dentro de un agente de programación, Proxy Toolkit MCP acepta descripciones de errores saneadas. Mantén las credenciales y las URL privadas fuera de sus argumentos y verifica los cambios sugeridos con una petición acotada.

El acceso a los proxies de ipvolt todavía no está abierto. Entérate de cuándo se abre el acceso. Un correo cuando se abra el acceso. Nada más.