Node.js Proxy Setup: Axios, Fetch, Undici & Rotatie

De axios proxy-optie is een valkuil voor HTTPS-doelen, en native fetch negeert je proxy-omgevingsvariabelen volledig. Hier is de setup die werkt voor axios, fetch en undici — agents, authenticatie, SOCKS5, rotatie en streaming.

Het routeren van Node.js-verzoeken via een proxy lijkt een eenregelige opdracht en verandert in een middag debuggen. De reden is dat de drie HTTP-clients die de meeste projecten gebruiken — axios, de native fetch die als een globale in Node 18 is geleverd, en de onderliggende undici-bibliotheek — elk een proxy anders accepteren, en geen van hen gedraagt zich zoals je verwacht. Axios heeft een ingebouwde proxy configuratie die gedocumenteerd is, alleen voor Node, en stilletjes kapot is voor HTTPS-doelen achter een HTTP-proxy: een bug die sinds 2020 openstaat op de axios GitHub-tracker en een sterk geüpvote Stack Overflow-thread heeft veroorzaakt. Ondertussen negeert native fetch HTTP_PROXY omgevingsvariabelen en heeft helemaal geen proxy-optie. Deze gids geeft je de setup die daadwerkelijk werkt in elke client, plus authenticatie, SOCKS5, rotatie en streaming.

Axios proxy configuratie versus proxy agents

Axios wordt geleverd met een proxy object — { host, port, auth } — en het werkt prima voor gewone HTTP-doelen. De valkuil is HTTPS: wanneer het doel https:// is en de proxy spreekt HTTP, slaagt axios er niet in om de CONNECT-tunnel te openen en je verzoek blijft hangen of komt terug met je echte IP. De oplossing waar de gemeenschap op uitkwam, is om de ingebouwde configuratie volledig te omzeilen en axios een proxy-agent te geven, en vervolgens proxy: false in te stellen zodat de twee mechanismen niet botsen:

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>" }

Twee details besparen uren. Ten eerste, gebruik de gedestructureerde { HttpsProxyAgent } import — recente versies exporteren het als een benoemd symbool, en een standaardimport geeft je een object dat een fout geeft bij constructie. Ten tweede, het proxy-URL-schema blijft http:// zelfs wanneer de proxy HTTPS-verkeer draagt: het schema beschrijft hoe je de proxy bereikt, en de TLS naar het doel loopt binnen de tunnel. Dezelfde foutklasse verschijnt in Python; als je ook werkt in requests, rijmen de patronen met onze ProxyError en SSLError fix gids.

Authenticatie en omgevingsvariabelen

Geauthenticeerde proxies gebruiken HTTP Basic-credentials. Met een agent, embed ze in de URL als http://user:pass@host:port; als het wachtwoord @, : of / bevat, URL-encodeer het eerst met encodeURIComponent() of de URL splitst op de verkeerde plaats. Een 407 Proxy Authentication Required betekent dat de credentials zijn afgewezen of dat je bron-IP niet op de witte lijst staat. Axios leest ook HTTP_PROXY, HTTPS_PROXY en NO_PROXY uit de omgeving — handig voor het proxyen van een externe bibliotheek zonder de code aan te raken — en je schakelt dat uit door proxy: false in te stellen. De belangrijke waarschuwing: native fetch leest deze variabelen niet, dus een scraper die vertrouwt op env-var proxying gaat stilletjes direct zodra je overschakelt van axios naar fetch.

Proxying native fetch met undici

Node's globale fetch is gebouwd op undici, en undici is waar de proxy leeft. Je maakt een ProxyAgent en geeft die door als de niet-standaard dispatcher optie — dit is de moderne, lichte manier om fetch te proxyen, en het handelt HTTPS CONNECT correct af zonder extra configuratie:

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());

Als je direct op undici zit in plaats van globale fetch, sluit dezelfde ProxyAgent aan op request() of op setGlobalDispatcher() om elke fetch in het proces in één keer te proxyen. Die eenmalige globale schakelaar is de schoonste manier om een hele codebase door een proxy te routeren zonder een dispatcher door elke functie te moeten leiden.

SOCKS5 proxies in Node.js

Noch axios noch undici spreekt SOCKS native — geef een socks5:// string door aan de axios proxy configuratie en je krijgt een protocol mismatch bewering. Installeer socks-proxy-agent en gebruik het op dezelfde manier als de HTTPS-agent, aangesloten op zowel httpAgent als httpsAgent. Geef de voorkeur aan socks5h:// boven socks5://: de achtervoegsel h lost DNS op aan de proxyzijde, wat DNS-lekken voorkomt en geo-afgeschermde hostnamen oplost vanaf de uitgangslocatie. Elk SOCKS5 proxy plan stelt dezelfde gateway bloot over HTTP en SOCKS5, dus dit is een schema-wissel, geen nieuwe aankoop:

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);

Rotatie zonder een proxy-lijst

Het oude recept — een array van IP's, Math.random() per verzoek, verwijder de dode — is code die je niet langer onderhoudt. Een roterende gateway wijst een vers exit-IP toe aan de serverzijde bij elk verzoek, zodat één eindpunt zich gedraagt als een hele pool. Via roterende residentiële proxies bestrijkt die pool 90M+ IP's over 200+ landen, en de lus hieronder print een andere oorsprong bij elke iteratie zonder rotatielogica:

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
}

Wanneer een flow meerdere verzoeken omvat — inloggen, toevoegen aan winkelwagen, afrekenen — breekt rotatie per verzoek de sessie. Een sticky sessieparameter in de proxygebruikersnaam pinnen één exit-IP voor een vast venster, en roteert dan; hetzelfde eindpunt, één stringwijziging. Als je dit opschaalt naar duizenden gelijktijdige verzoeken, verplaats het werk dan van axios-lussen en lees onze gids over grootschalige scraping-architectuur voor wachtrijen en gelijktijdigheidsbudgetten.

Streaming reacties via een proxy

Bestanden of grote JSON-payloads downloaden werkt hetzelfde als elk verzoek zodra de agent is aangesloten — stel responseType: "stream" in en leid het lichaam naar de schijf. De proxy handelt de overdracht transparant af, zodat een export van 200MB nooit in het geheugen buffert:

import fs from "node:fs";

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

Veelgestelde vragen

Waarom werkt mijn axios proxy niet?

De meest voorkomende oorzaak is een HTTPS-doel achter een HTTP-proxy: de ingebouwde proxy configuratie van axios slaagt er niet in om de CONNECT-tunnel te openen en retourneert je echte IP of blijft hangen. Schakel over naar een proxy-agent — koppel HttpsProxyAgent aan httpAgent en httpsAgent, en stel proxy: false in zodat axios stopt met proberen de proxy zelf af te handelen.

Ondersteunt axios SOCKS5 proxies?

Niet native — het doorgeven van een socks5:// URL aan de proxy configuratie geeft een protocol-mismatch fout. Installeer socks-proxy-agent, bouw een SocksProxyAgent, en sluit het aan op zowel httpAgent als httpsAgent. Gebruik het socks5h:// schema zodat DNS wordt opgelost aan de proxyzijde in plaats van te lekken vanaf je machine.

Hoe gebruik ik een proxy met native fetch in Node.js?

Native fetch heeft geen proxy-optie en negeert HTTP_PROXY omgevingsvariabelen. Maak een undici ProxyAgent en geef die door als de dispatcher optie bij de fetch-aanroep, of roep setGlobalDispatcher() eenmaal aan om elke fetch in het proces te proxyen. Undici handelt HTTPS CONNECT correct af zonder extra configuratie.

Hoe stel ik een axios proxy in met omgevingsvariabelen?

Exporteer HTTP_PROXY, HTTPS_PROXY en optioneel NO_PROXY met volledige proxy-URL's; axios leest ze automatisch. Stel proxy: false in op een verzoek of instantie om axios de omgeving te laten negeren. Vergeet niet dat dit alleen axios beïnvloedt — undici en native fetch zullen die variabelen niet oppikken.

Het hele verhaal past op een kaart: axios heeft een agent en proxy: false nodig, native fetch heeft een undici dispatcher nodig, SOCKS heeft zijn eigen agent nodig, en rotatie hoort op de gateway in plaats van in je lus. Krijg de leidingen goed en de laatste variabele is IP-kwaliteit — een schone residentiële exit slaagt waar een gemarkeerd datacenter-IP een 403 krijgt op dezelfde code.

Krijg residentiële proxies die slagen bij het eerste verzoek