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:

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@gate.quantumproxies.io:PORT");

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.

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.

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:

import { ProxyAgent } from "undici";

const dispatcher = new ProxyAgent({
  uri: "http://gate.quantumproxies.io:PORT",
  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 espone lo stesso gateway su HTTP e SOCKS5, quindi questo è uno scambio di schema, non un nuovo acquisto:

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

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

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 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:

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

const agent = new HttpsProxyAgent("http://USER:PASS@gate.quantumproxies.io:PORT");
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 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:

import fs from "node:fs";

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

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