# Configurazione Proxy Node.js: Axios, Fetch, Undici e Rotazione

L'opzione proxy di axios è una trappola per i target HTTPS, e il fetch nativo ignora completamente le variabili d'ambiente del tuo proxy. Ecco la configurazione che funziona su axios, fetch e undici — agenti, autenticazione, SOCKS5, rotazione e streaming.

Instradare le richieste Node.js attraverso un proxy sembra una riga di codice e si trasforma in un pomeriggio di debugging. Il motivo è che i tre client HTTP più utilizzati nei progetti — axios, il `fetch` nativo introdotto come globale in Node 18, e la libreria sottostante undici — accettano un proxy in modo diverso, e nessuno di loro si comporta come ci si aspetta. Axios ha una configurazione `proxy` integrata che è documentata, solo per Node, e silenziosamente difettosa per i target HTTPS dietro un proxy HTTP: un bug aperto sul tracker GitHub di axios dal 2020 che ha generato un thread molto votato su Stack Overflow. Nel frattempo, il fetch nativo ignora le variabili d'ambiente `HTTP_PROXY` e non ha alcuna opzione proxy. Questa guida ti fornisce la configurazione che funziona effettivamente in ciascun client, oltre ad autenticazione, SOCKS5, rotazione e streaming.

## Configurazione proxy axios vs agenti proxy

Axios include un oggetto `proxy` — `{ host, port, auth }` — e funziona bene per i target HTTP semplici. La trappola è HTTPS: quando il target è `https://` e il proxy parla HTTP, axios non riesce ad aprire il tunnel CONNECT e la tua richiesta si blocca o ritorna con il tuo IP reale. La soluzione che la comunità ha adottato è di bypassare completamente la configurazione integrata e fornire ad axios un agente proxy, quindi impostare `proxy: false` in modo che i due meccanismi non si scontrino:

```js
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

// Note the destructured import — a default import is the classic gotcha.
const agent = new HttpsProxyAgent("http://USER:PASS@residentialpremium.quantumproxies.io:8080");

const client = axios.create({
  httpAgent: agent,   // for http:// targets
  httpsAgent: agent,  // for https:// targets
  proxy: false,       // disable axios' own broken proxy handling
  timeout: 15000,
});

const r = await client.get("https://httpbin.org/ip");
console.log(r.data); // { origin: "<proxy exit IP>" }
```

Due dettagli ti risparmiano ore. Primo, usa l'importazione **distrutturata** `{ HttpsProxyAgent }` — le versioni recenti lo esportano come simbolo nominato, e un'importazione predefinita ti dà un oggetto che genera un'eccezione quando costruito. Secondo, lo schema URL del proxy rimane `http://` anche quando il proxy trasporta traffico HTTPS: lo schema descrive come raggiungi il proxy, e il TLS verso il target avviene all'interno del tunnel. La stessa classe di errore si presenta in Python; se lavori anche con requests, i pattern risuonano con la nostra [guida alla risoluzione di ProxyError e SSLError](https://quantumproxies.io/blog/python-requests-proxyerror-fix).

## Autenticazione e variabili d'ambiente

I proxy autenticati utilizzano credenziali HTTP Basic. Con un agente, incorporale nell'URL come `http://user:pass@host:port`; se la password contiene `@`, `:` o `/`, codificala nell'URL con `encodeURIComponent()` prima o l'URL si divide nel punto sbagliato. Un `407 Proxy Authentication Required` significa che le credenziali sono state rifiutate o il tuo IP sorgente non è nella whitelist. Axios legge anche `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY` dall'ambiente — utile per proxyare una libreria di terze parti senza toccare il suo codice — e puoi disabilitarlo impostando `proxy: false`. L'avvertimento importante: il `fetch` nativo **non** legge queste variabili, quindi uno scraper che si basa sul proxying tramite variabili d'ambiente va direttamente nel momento in cui passi da axios a fetch.

![Tre snippet di codice per la stessa richiesta: axios accetta un HttpsProxyAgent su httpAgent e httpsAgent con proxy: false, fetch nativo accetta un dispatcher undici per chiamata, e setGlobalDispatcher di undici con un ProxyAgent mette dietro proxy l'intero processo. Confonderli è la causa principale di 'proxy not working'.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785335145/blog/generated/qp-b9-007-diag1.png)
*Stessa richiesta, tre sistemi di tubature. Axios vuole un agente, il fetch nativo vuole un dispatcher undici, e mescolarli è la causa numero uno di 'proxy non funzionante'.*

## Proxying fetch nativo con undici

Il `fetch` globale di Node è costruito su undici, ed è lì che vive il proxy. Crei un `ProxyAgent` e lo passi come opzione non standard `dispatcher` — questo è il modo moderno e leggero in termini di dipendenze per proxyare fetch, e gestisce correttamente HTTPS CONNECT senza configurazioni aggiuntive:

```js
import { ProxyAgent } from "undici";

const dispatcher = new ProxyAgent({
  uri: "http://residentialpremium.quantumproxies.io:8080",
  token: "Basic " + Buffer.from("USER:PASS").toString("base64"),
});

const res = await fetch("https://httpbin.org/ip", { dispatcher });
console.log(await res.json());
```

Se stai usando undici direttamente piuttosto che fetch globale, lo stesso `ProxyAgent` si collega a `request()` o a `setGlobalDispatcher()` per proxyare ogni fetch nel processo in una volta sola. Quello switch globale a chiamata singola è il modo più pulito per instradare un intero codice attraverso un proxy senza passare un dispatcher attraverso ogni funzione.

## Proxy SOCKS5 in Node.js

Né axios né undici parlano SOCKS nativamente — passa una stringa `socks5://` alla configurazione `proxy` di axios e ottieni un'asserzione di `protocol mismatch`. Installa `socks-proxy-agent` e usalo allo stesso modo dell'agente HTTPS, collegato sia a `httpAgent` che a `httpsAgent`. Preferisci `socks5h://` a `socks5://`: la `h` finale risolve il DNS sul lato proxy, il che impedisce perdite DNS e risolve i nomi host geo-restritti dalla posizione di uscita. Ogni piano [SOCKS5 proxy](https://quantumproxies.io/socks5-proxies) espone lo stesso gateway su HTTP e SOCKS5, quindi questo è uno scambio di schema, non un nuovo acquisto:

```js
import axios from "axios";
import { SocksProxyAgent } from "socks-proxy-agent";

const agent = new SocksProxyAgent("socks5h://USER:PASS@residentialpremium.quantumproxies.io:1080");

const client = axios.create({ httpAgent: agent, httpsAgent: agent });
const r = await client.get("https://httpbin.org/ip");
console.log(r.data);
```

## Rotazione senza una lista di proxy

La vecchia ricetta — un array di IP, `Math.random()` per richiesta, elimina quelli morti — è codice che non mantieni più. Un gateway rotante assegna un IP di uscita fresco lato server ad ogni richiesta, quindi un endpoint si comporta come un intero pool. Attraverso [proxy residenziali rotanti](https://quantumproxies.io/rotating-proxies) quel pool si estende su oltre 90 milioni di IP in più di 200 paesi, e il loop sotto stampa un'origine diversa ad ogni iterazione senza logica di rotazione:

```js
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const agent = new HttpsProxyAgent("http://USER:PASS@residentialpremium.quantumproxies.io:8080");
const client = axios.create({ httpAgent: agent, httpsAgent: agent, proxy: false });

for (let i = 0; i < 3; i++) {
  const r = await client.get("https://httpbin.org/ip");
  console.log(r.data.origin); // a different exit IP each time
}
```

Quando un flusso comprende diverse richieste — login, aggiungi al carrello, checkout — la rotazione per richiesta rompe la sessione. Un parametro di sessione sticky nel nome utente del proxy fissa un IP di uscita per una finestra impostata, poi ruota; stesso endpoint, un cambio di stringa. Se stai scalando questo in migliaia di richieste concorrenti, sposta il lavoro fuori dai loop di axios e leggi la nostra guida all'[architettura di scraping su larga scala](https://quantumproxies.io/blog/large-scale-web-scraping-architecture) per code e budget di concorrenza.

## Streaming di risposte attraverso un proxy

Scaricare file o payload JSON di grandi dimensioni funziona come qualsiasi richiesta una volta che l'agente è collegato — imposta `responseType: "stream"` e indirizza il corpo su disco. Il proxy gestisce il trasferimento in modo trasparente, quindi un'esportazione di 200MB non viene mai bufferizzata in memoria:

```js
import fs from "node:fs";

const r = await client.get("https://example.com/large.json", {
  responseType: "stream",
});
r.data.pipe(fs.createWriteStream("out.json"));
```

![Una pagina httpbin.org/ip mostra quattro errori proxy in Node.js: la configurazione proxy di axios che restituisce il tuo IP reale o si blocca, un import predefinito dell'agent che genera un errore, socks5:// in axios che causa un'incongruenza di protocollo, e fetch che ignora HTTP_PROXY. La scheda dà ogni soluzione e una nota mette in guardia dal raddoppiare agent e configurazione proxy.](https://res.cloudinary.com/dmqliab0t/image/upload/f_auto,q_auto,w_1200/v1785335146/blog/generated/qp-b9-007-diag2.png)
*La maggior parte dei fallimenti proxy Node.js si riduce a cinque errori: il bug HTTPS di axios, un'importazione predefinita dell'agente, configurazione proxy duplicata, schema SOCKS errato, o aspettarsi che fetch legga le variabili d'ambiente.*

## Domande frequenti

### Perché il mio proxy axios non funziona?

La causa più comune è un target HTTPS dietro un proxy HTTP: la configurazione `proxy` integrata di axios non riesce ad aprire il tunnel CONNECT e restituisce il tuo IP reale o si blocca. Passa a un agente proxy — collega `HttpsProxyAgent` a `httpAgent` e `httpsAgent`, e imposta `proxy: false` in modo che axios smetta di gestire il proxy da solo.

### Axios supporta i proxy SOCKS5?

Non nativamente — passare un URL `socks5://` alla configurazione `proxy` genera un errore di incompatibilità di protocollo. Installa `socks-proxy-agent`, costruisci un `SocksProxyAgent`, e collegalo sia a `httpAgent` che a `httpsAgent`. Usa lo schema `socks5h://` in modo che il DNS venga risolto sul lato proxy piuttosto che trapelare dalla tua macchina.

### Come uso un proxy con fetch nativo in Node.js?

Il fetch nativo non ha un'opzione proxy e ignora le variabili d'ambiente `HTTP_PROXY`. Crea un `ProxyAgent` undici e passalo come opzione `dispatcher` nella chiamata fetch, o chiama `setGlobalDispatcher()` una volta per proxyare ogni fetch nel processo. Undici gestisce correttamente HTTPS CONNECT senza configurazioni aggiuntive.

### Come imposto un proxy axios con variabili d'ambiente?

Esporta `HTTP_PROXY`, `HTTPS_PROXY` e opzionalmente `NO_PROXY` con URL proxy completi; axios li legge automaticamente. Imposta `proxy: false` su una richiesta o istanza per far ignorare ad axios l'ambiente. Ricorda che questo riguarda solo axios — undici e fetch nativo non prenderanno quelle variabili.

L'intera storia sta su una scheda: axios ha bisogno di un agente e `proxy: false`, fetch nativo ha bisogno di un dispatcher undici, SOCKS ha bisogno del suo agente, e la rotazione appartiene al gateway piuttosto che nel tuo loop. Sistema le tubature e l'ultima variabile è la qualità dell'IP — un'uscita residenziale pulita passa dove un IP di datacenter segnalato ottiene un 403 sullo stesso codice.

[Ottieni proxy residenziali che passano alla prima richiesta](https://quantumproxies.io/residential-proxies)