¿Qué es el proxy de Node.js y cómo utilizar servidores proxy en Node.js?
Resumen
Node.js no tiene soporte de proxy integrado. Los módulos http/https envían solicitudes directamente al host de destino a menos que adjuntes un http.Agent compatible con proxy o configures las opciones de la solicitud tú mismo.
Las variables de entorno HTTP_PROXY/HTTPS_PROXY solo funcionan si la biblioteca que llamas las lee. El http.request básico las ignora por completo; la mayoría de las herramientas de línea de comandos y algunos clientes HTTP las leen a través de paquetes auxiliares, no automáticamente.
https-proxy-agent y http-proxy-agent son la forma estándar de enrutar solicitudes básicas http/https a través de un proxy, utilizando un túnel CONNECT de HTTP para objetivos HTTPS y reenvío directo para objetivos HTTP.
Axios acepta un objeto proxy directamente (host, port, protocol, auth opcional), por lo que la mayoría de los proyectos basados en Axios no necesitan un paquete de agente separado para proxies HTTP.
El nativo y enrutan a través de un proxy mediante y , lo que también afecta el global de Node desde la versión 18+, ya que se basa en undici.
Las credenciales del proxy deben estar en la URL del proxy o en un campo de autenticación dedicado, nunca codificadas de manera fija en el código de la aplicación que se envía al control de versiones.
Los proxies SOCKS5 necesitan un agente diferente (socks-proxy-agent) porque los agentes de proxy HTTP basados en CONNECT no entienden el apretón de manos SOCKS.
Introducción: qué significa "proxy" para una solicitud de Node.js
Un proxy en Node.js es un servidor intermediario al que un script enruta deliberadamente una solicitud HTTP o HTTPS saliente, en lugar de conectarse directamente al host de destino. Los módulos básicos http y https de Node no fueron diseñados con soporte de proxy como comportamiento predeterminado: cada solicitud proxied en Node.js funciona porque el código (o una biblioteca) apunta explícitamente la solicitud a un host de proxy, ya sea a través de un http.Agent personalizado o mediante una configuración específica del cliente.
Esa distinción es importante porque explica por qué copiar un tutorial de proxy escrito para un cliente HTTP en un proyecto que utiliza un cliente diferente a menudo no funciona. curl y muchas herramientas del sistema leen HTTP_PROXY/HTTPS_PROXY automáticamente del entorno; el http.request de Node no lo hace. Cada biblioteca de cliente a continuación necesita su propia configuración explícita.
Echa un vistazo rápido
Integrar credenciales de proxy y lógica de rotación en cada solicitud es fácil de hacer mal a mano: Nstproxy emite un punto final estable de gateway por plan, por lo que tu código en Node.js solo tiene que apuntar a una URL de proxy.
Node.js incluye http, https y (desde Node 18 en adelante) un fetch global respaldado por ProxyAgent de undici. Ninguno de ellos incluye código de enrutamiento de proxy, así que agrega el paquete de agente que coincida con el cliente que ya utilizas:
No necesitas los cinco en un solo proyecto: instala solo los paquetes para el(los) cliente(s) que tu código realmente llama. La versión 9.1.0 de https-proxy-agent y la versión 9.1.0 de http-proxy-agent exportan una clase nombrada (HttpsProxyAgent, HttpProxyAgent) en lugar de una exportación por defecto, lo cual es importante para la sintaxis de require/import a continuación.
Configura un proxy para los módulos básicos http/https de Node
http-proxy-agent reenvía solicitudes HTTP simples a través del proxy; https-proxy-agent abre un túnel CONNECT de HTTP a través del proxy y luego negocia TLS con el destino, lo cual es lo que requiere un objetivo HTTPS. Pasar el agente resultante como la opción agent en las funciones de solicitud basadas en http.Agent de Node es el único cambio a una llamada normal de https.request:
Este ejemplo se ejecutó contra un proxy de prueba local (un Node http.createServer manejando CONNECT) y un destino HTTPS local: la solicitud devolvió 200 y el cuerpo JSON esperado a través del túnel, confirmando que el flujo CONNECT-luego-TLS funciona con esta versión exacta del agente y forma de llamada.
Para un destino HTTP simple (no HTTPS), usa HttpProxyAgent en su lugar: este retransmite la solicitud sin un apretón de manos CONNECT:
Ejecutar una llamada http.get() sin modificar contra el mismo destino sin la opción agent, y con HTTP_PROXY configurado solo como una variable de entorno, confirmó que el núcleo http ignora la variable de entorno: la solicitud fue directamente al destino en lugar de a través del proxy. Considera cualquier tutorial que te diga que "solo configures HTTP_PROXY" para el núcleo http/https como incompleto; solo funciona para herramientas que leen específicamente esa variable.
Configurar un proxy en Axios
Axios (probado en la versión 1.19.0) acepta configuraciones de proxy como un objeto simple en la configuración de la solicitud, sin paquete de agente adicional requerido para proxies de esquema HTTP:
Esta solicitud se ejecutó contra el mismo proxy local y objetivo utilizados anteriormente y devolvió 200 con el cuerpo esperado, confirmando que la opción proxy de Axios realiza el túnel CONNECT para un objetivo HTTPS por su cuenta. Si necesitas opciones TLS que el objeto proxy de Axios no expone — un CA personalizado, o deshabilitar la verificación de certificados contra un host de prueba interno — pasa httpsAgent: new https.Agent({...}) junto con proxy, o reemplaza proxy completamente con una instancia de https-proxy-agent asignada a httpsAgent.
Axios también respeta las variables de entorno HTTP_PROXY/HTTPS_PROXY/NO_PROXY por defecto, a menos que se configure proxy: false en la configuración de la solicitud — este es uno de los pocos clientes donde la convención de variables de entorno funciona sin que tengas que escribir código de agente.
Configurar un proxy para node-fetch y fetch nativo/undici
node-fetch (probado en la versión 2.7.0) toma la misma opción agent que el núcleo http/https, por lo que las mismas instancias de http-proxy-agent/https-proxy-agent se aplican:
Ejecutado contra el proxy de prueba local y un objetivo HTTP, este devolvió el cuerpo JSON esperado, confirmando que las mismas clases de agente funcionan sin cambios en el núcleo http y node-fetch.
El fetch() global integrado de Node (disponible desde Node 18 en adelante) y el paquete independiente undici no aceptan una opción agent de la misma manera: utilizan el propio ProxyAgent de undici, registrado globalmente con setGlobalDispatcher:
const{ProxyAgent, setGlobalDispatcher }=require('undici');setGlobalDispatcher(newProxyAgent('http://proxy.example.com:8000'));const res =awaitfetch('https://api.example.com/status');console.log(res.status,await res.json());
Esto se ejecutó con la versión 6.28.0 de undici: después de llamar a setGlobalDispatcher, tanto undici.request() como el fetch() global de Node se dirigieron a través del proxy de prueba local y devolvieron la respuesta esperada 200 — confirmando que setGlobalDispatcher afecta el fetch global, no solo las propias funciones de solicitud de undici, porque la implementación de fetch de Node se basa en undici. Limita un ProxyAgent a una sola solicitud en lugar de configurarlo globalmente cuando solo algunas solicitudes en un proceso necesitan pasar por el proxy — pasa { dispatcher: new ProxyAgent(...) } como una opción por llamada a undici.request().
Patrones avanzados: autenticación, SOCKS5 y rotación
Autenticación de proxy. Para los cuatro clientes anteriores, incrusta credenciales en la URL del proxy (http://user:pass@proxy.example.com:8000) o en el campo de autenticación dedicado del cliente (el auth de proxy de Axios). Nunca las formatees en el propio encabezado Authorization de la solicitud de destino — ese encabezado va al servidor de destino, no al proxy, y la mayoría de los servidores proxy esperan credenciales en un encabezado Proxy-Authorization, que los paquetes de agente construyen para ti a partir de la información del usuario de la URL.
Proxies SOCKS5.https-proxy-agent y http-proxy-agent solo implementan el protocolo de proxy HTTP CONNECT. Un endpoint SOCKS5 necesita socks-proxy-agent, que expone el mismo patrón de opción agent:
Control de sesión (pegajosa vs. rotativa). Si una solicitud dada reutiliza la misma IP de salida que la anterior o obtiene una nueva, está controlado por la puerta de enlace del proveedor de proxy, no por Node.js — el código del lado del cliente arriba se mantiene idéntico de cualquier manera. Los proveedores que soportan ambos modos generalmente cambian el comportamiento en función de un parámetro de sesión añadido al nombre de usuario del proxy (un ID de "sesión pegajosa") o en puertos de puerta de enlace separados para grupos pegajosos vs. rotativos; consulta la documentación de la puerta de enlace del proveedor específico para conocer el nombre exacto del parámetro antes de asumir que una convención de un proveedor se aplica a otro.
Usando Nstproxy con los mismos patrones
Nstproxy proporciona puntos de acceso HTTP/SOCKS5 a través de Residential Lite Proxies y seis otras líneas de productos de proxy: Residential Prime, Datacenter, Static ISP, IPv6, Unlimited Residential y Mobile — así que el mismo código HttpsProxyAgent/Axios proxy/ProxyAgent anterior funciona apuntando el agente a tu host, puerto y credenciales de puerta de enlace Nstproxy asignados en lugar de un marcador de posición. Nstproxy está diseñado para equipos que necesitan segmentación geográfica, control de sesión o un volumen de solicitudes más alto del que un único proxy autoalojado puede sostener, y se adapta a cargas de trabajo de scraping, monitoreo de precios, verificación de anuncios y pruebas de QA donde una sola IP de salida sería limitada o bloqueada.
Segmentación por país y ciudad — selecciona una ubicación de salida al incluir un parámetro de ubicación en el nombre de usuario del proxy, sin cambiar ningún código de solicitud del lado del cliente.
Sesiones pegajosas o rotativas — mantiene una IP para un flujo de trabajo de varios pasos (iniciar sesión, luego paginar) o rota por solicitud, según el parámetro de sesión utilizado.
Puertas de enlace HTTP y SOCKS5 — el mismo código del cliente mostrado arriba (basado en agente para http/node-fetch, objeto proxy nativo para Axios, ProxyAgent para undici/fetch) funciona contra la puerta de enlace de Nstproxy sin más cambios.
Confirma los nombres de host, puertos y precios actuales de la puerta de enlace en la página de precios de Residential Lite Proxies antes de aprovisionar, ya que los detalles de la puerta de enlace y las tarifas están sujetos a cambios. Todos los parámetros de la puerta de enlace, formatos de autenticación y fragmentos de SDK están en la documentación de Nstproxy; si primero estás decidiendo entre proveedores de proxy, la página de comparación de proxies de Nstproxy expone las diferencias de características en comparación con otros proveedores. Los equipos que combinan tráfico de proxy con un crawler de Node.js a menudo centralizan las reglas de enrutamiento y la supervisión de grupos a continuación — consulta cómo Nstproxy Proxy Manager se aplica a cargas de trabajo de crawling para esa capa.
Límites honestos
http/https y node-fetch en su núcleo nunca leen HTTP_PROXY/HTTPS_PROXY por sí mismos — cada ejemplo anterior establece explícitamente el proxy en el código, y cualquier implementación que confíe únicamente en la variable de entorno para estos clientes ignorará silenciosamente el proxy.
El túnel CONNECT de https-proxy-agent añade un viaje de red extra por cada nueva conexión HTTPS en comparación con una solicitud directa; la reutilización de conexiones (keepAlive: true en el agente) amortiza ese costo a través de múltiples solicitudes al mismo host.
Ninguno de los paquetes de agente anteriores reintenta una conexión de proxy fallida o rota automáticamente a una IP de salida diferente — esa lógica, si la necesitas, debe ser escrita en tu propio envoltorio de solicitud o proporcionada por la puerta de enlace del servicio de proxy.
Las conexiones WebSocket necesitan su propio manejo de actualización consciente del proxy; los agentes mostrados aquí cubren ciclos de solicitud/respuesta HTTP/HTTPS sencillos, no el apretón de manos Upgrade.
Solución de problemas
ECONNREFUSED o ECONNRESET al conectar a través del proxy. Confirma que el host y el puerto del proxy son alcanzables directamente (por ejemplo, con nc -vz host puerto) antes de asumir que el código de Node.js está mal — un firewall o una sesión de proxy expirada produce el mismo error que un error de código.
Errores unable to verify the first certificate o self-signed certificate. Esto significa que el cliente está validando TLS para el host de destino a través del túnel y falla, generalmente porque un proxy corporativo o de prueba está interceptando TLS con su propio certificado. Agrega ese certificado al almacén de confianza de Node (NODE_EXTRA_CA_CERTS) en lugar de deshabilitar la validación de certificados en código de producción.
Las solicitudes se cuelgan en lugar de fallar. Establece un tiempo de espera explícito en el agente o el cliente (opción timeout en http.request, timeout en Axios) — los proxies que silenciosamente descartan paquetes en lugar de devolver un error de conexión rechazada se colgarán hasta que se agote el tiempo de espera predeterminado de socket de la plataforma.
Solo algunas solicitudes utilizan el proxy. Para undici/global fetch, setGlobalDispatcher se aplica a cada llamada subsiguiente en el proceso; si algunas llamadas evitan el proxy inesperadamente, verifica si esa ruta de código utiliza un cliente HTTP diferente (Axios, node-fetch) que necesita su propia configuración de proxy separada.
Conclusión
Cada configuración de proxy en Node.js se reduce a la misma decisión: qué cliente HTTP está realizando la solicitud y cuál de los mecanismos de proxy admitidos de ese cliente — un http.Agent explícito, un objeto de configuración proxy, o un despachador global — configuras con el host, puerto y credenciales de destino. El núcleo http/https y node-fetch necesitan un agente de https-proxy-agent/http-proxy-agent/socks-proxy-agent; Axios acepta un objeto proxy directamente; fetch nativo y undici pasan a través de ProxyAgent y setGlobalDispatcher. Ninguno de ellos funciona solo a través de la variable de entorno HTTP_PROXY, a menos que el cliente específico documente que la lee.
Preguntas frecuentes
P: ¿Node.js admite proxies de forma nativa?
No: los módulos http y https básicos se conectan directamente al host de destino a menos que la solicitud utilice explícitamente un http.Agent que reconozca proxies (de un paquete como https-proxy-agent) o la biblioteca cliente tenga su propia configuración de proxy, como la opción proxy de Axios.
P: ¿Por qué no funciona configurar HTTP_PROXY en mi script de Node.js?
Configurar HTTP_PROXY solo funciona para clientes que lo leen específicamente — Axios lo lee por defecto, pero el núcleo http/https y node-fetch no lo hacen, por lo tanto, necesitan un agente explícito en el código independientemente de las variables de entorno.
P: ¿Cuál es la diferencia entre http-proxy-agent y https-proxy-agent?
http-proxy-agent retransmite una solicitud HTTP simple a través del proxy sin un túnel, mientras que https-proxy-agent primero abre un túnel HTTP CONNECT a través del proxy y luego negocia TLS con el destino HTTPS — utiliza el que coincida con el esquema de tu objetivo, no el esquema de tu proxy.
P: ¿Puedo usar un proxy con el fetch() nativo de Node?
Sí: registra un ProxyAgent de undici con setGlobalDispatcher() antes de llamar a fetch(), ya que el fetch incorporado de Node se ejecuta en undici y lee el mismo despachador global.
P: ¿Necesito una configuración diferente para un proxy SOCKS5?
Sí: https-proxy-agent y http-proxy-agent solo implementan el protocolo proxy HTTP CONNECT, por lo que un punto final SOCKS5 necesita socks-proxy-agent en su lugar, utilizando el mismo patrón de opción agent.
P: ¿Es seguro codificar las credenciales del proxy en mi código de Node.js?
No: mantén los nombres de usuario y contraseñas del proxy en variables de entorno o en un gestor de secretos y construye la URL del proxy en tiempo de ejecución, de la misma manera que manejarías una contraseña de base de datos, en lugar de comprometerlas en el control de versiones.
P: ¿Un proxy ralentizará mis solicitudes de Node.js?
Una solicitud HTTPS a través de un túnel HTTP CONNECT añade una ronda adicional para establecer el túnel en comparación con una conexión directa, pero habilitar keepAlive en el agente permite que las solicitudes subsiguientes al mismo host reutilicen ese túnel en lugar de volver a pagar el costo.
Chrome no tiene configuraciones de proxy integradas; le deja el trabajo a su sistema operativo. Aquí está la ruta exacta de configuración para Windows, macOS, Linux y ChromeOS, además de las opciones de línea de comandos, SOCKS5, archivos PAC y el manejo de proxy autenticados que la mayoría de las guías omiten.
Ivy Lin
Aug. 7th 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.