# Usar un proxy con fetch de Node.js

Source: https://ipvolt.com/es/guides/nodejs-fetch-proxy
Markdown: https://ipvolt.com/es/guides/nodejs-fetch-proxy.md
Language: es

[Inicio de ipvolt](https://ipvolt.com/es.md) / [Guías](https://ipvolt.com/es/guides.md) / Usar un proxy con fetch de Node.js

Integración
Revisado: 2026-09-10
4 min de lectura
Por ipvolt

Enruta el fetch nativo de Node.js a través de un ProxyAgent de Undici con autenticación explícita, un plazo de cancelación y limpieza de la respuesta.

## El punto de partida

Usa un dispatcher para una sola llamada a fetch, de modo que el proxy sea explícito y los demás clientes de red de tu proceso conserven su propia configuración.

## Elige un runtime y un dispatcher compatibles

Este ejemplo del lado del servidor está pensado para Node.js 24 y Undici 7. En un proyecto de ejemplo aparte, ejecuta npm install undici@7. El fetch integrado de Node acepta un dispatcher compatible con Undici. Esto es distinto del fetch del navegador, donde el JavaScript de la página no puede seleccionar un proxy del sistema arbitrario.

Usa un gateway HTTP(S) documentado por tu proveedor en PROXY_URL, por ejemplo el https://proxy.example.invalid:8443 que a propósito no funciona. Inyecta PROXY_USERNAME y PROXY_PASSWORD a través del gestor de secretos de tu despliegue. No pongas credenciales del gateway en código de frontend.

## Mantén la autenticación del proxy en el dispatcher

Guárdalo como proxy-check.mjs y ejecuta node proxy-check.mjs. El token Basic pertenece al agente del proxy, no a la cabecera Authorization del destino. La petición tiene un plazo de cancelación de 30 segundos y no sigue redirecciones automáticamente.

### proxy-check.mjs · Node.js 24 + Undici 7

```javascript
import { ProxyAgent } from 'undici';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error('Missing environment variable: ' + name);
  return value;
}

const gateway = new URL(required('PROXY_URL'));
if (!['http:', 'https:'].includes(gateway.protocol) || gateway.username || gateway.password) {
  throw new Error('Use a credential-free HTTP(S) proxy URL');
}
const credentials = required('PROXY_USERNAME') + ':' + required('PROXY_PASSWORD');
const dispatcher = new ProxyAgent({
  uri: gateway.href,
  token: 'Basic ' + Buffer.from(credentials).toString('base64'),
});

try {
  const response = await fetch('https://example.com/', {
    dispatcher,
    signal: AbortSignal.timeout(30_000),
    redirect: 'manual',
  });
  await response.body?.cancel();
  if (!response.ok) throw new Error('Destination HTTP ' + response.status);
  console.log({ status: response.status });
} finally {
  await dispatcher.close();
}
```

## Pasa de un diagnóstico a un worker

Este script cancela a propósito el cuerpo de la respuesta porque el diagnóstico solo necesita un estado. Un worker que use el resultado debería consumir el cuerpo dentro de su presupuesto. Consúmelo o cancélalo siempre antes de continuar, y cierra el dispatcher cuando el worker se apague.

Para trabajos repetidos, reutiliza un dispatcher con concurrencia acotada en lugar de crear uno por petición. Mantén el plazo de cada trabajo por separado. No instales un dispatcher a nivel de proceso a menos que cambiar el enrutamiento de todos los clientes afectados sea intencional.

- Un error HTTP es una respuesta; fetch no rechaza la promesa solo porque su estado sea 4xx o 5xx.
- Un rechazo del CONNECT puede aparecer como un fallo de fetch antes de que exista una Response del destino.
- Captura categorías de error sin datos sensibles; no registres el token Basic ni URLs completas con credenciales.

## Antes de pasar a producción

- Usa las versiones mayores documentadas de Node y Undici.
- Pasa el dispatcher de forma explícita.
- Consume o cancela los cuerpos de respuesta y cierra el agente.

## Fuentes y lecturas adicionales

- [Node.js: fetch and custom dispatchers](https://nodejs.org/api/globals.html#fetch)
- [Undici 7: ProxyAgent authentication and lifecycle](https://github.com/nodejs/undici/blob/v7.16.0/docs/docs/api/ProxyAgent.md)
- [Undici: runtime support and response body handling](https://github.com/nodejs/undici)

## Guías relacionadas

- [Usar un proxy con curl: -x, variables de entorno, SOCKS5 y auth](https://ipvolt.com/es/guides/curl-proxy-setup.md)
- [Variables de entorno de proxy: HTTP_PROXY y NO_PROXY](https://ipvolt.com/es/guides/proxy-environment-variables.md)
- [Proxies HTTP vs SOCKS5: elige según la conexión](https://ipvolt.com/es/guides/http-vs-socks5-proxies.md)

## Sobre ipvolt

Los ejemplos usan configuraciones de proxy genéricas, con enlaces a la documentación técnica original. El comportamiento específico de cada producto debe comprobarse con tu proveedor. ipvolt sigue en desarrollo.

[Leer el original en inglés](https://ipvolt.com/guides/nodejs-fetch-proxy.md)

## Entérate cuando se abra el acceso.

ipvolt · En desarrollo

Estamos construyendo infraestructura de proxies para desarrolladores y equipos de datos. Únete a la lista de interés para recibir un aviso cuando ipvolt esté listo.

Un correo cuando se abra el acceso. Nada más.

[Solicitar acceso anticipado](https://ipvolt.com/es/guides/nodejs-fetch-proxy#waitlist-closing)

[Privacidad](https://ipvolt.com/privacy)