Node.js Proxy-Setup: Axios, Fetch, Undici & Rotation

Die axios proxy Option ist eine Falle bei HTTPS-Zielen, und der native fetch ignoriert Ihre Proxy-Umgebungsvariablen vollständig. Hier ist das Setup, das bei axios, fetch und undici funktioniert — Agents, Authentifizierung, SOCKS5, Rotation und Streaming.

Node.js-Anfragen über einen Proxy zu leiten, sieht aus wie eine Einzeiler und verwandelt sich in einen Nachmittag voller Debugging. Der Grund ist, dass die drei HTTP-Clients, die die meisten Projekte verwenden — axios, der native fetch, der als globales Element in Node 18 eingeführt wurde, und die zugrunde liegende undici-Bibliothek — jeden Proxy unterschiedlich behandeln, und keiner von ihnen sich so verhält, wie Sie es erwarten. Axios hat eine eingebaute proxy-Konfiguration, die dokumentiert ist, nur für Node gilt und leise für HTTPS-Ziele hinter einem HTTP-Proxy kaputt ist: ein Bug, der seit 2020 im axios GitHub-Tracker offen ist und einen stark bewerteten Stack Overflow-Thread ausgelöst hat. Der native fetch ignoriert unterdessen HTTP_PROXY-Umgebungsvariablen und hat überhaupt keine Proxy-Option. Diese Anleitung gibt Ihnen das Setup, das in jedem Client tatsächlich funktioniert, plus Authentifizierung, SOCKS5, Rotation und Streaming.

Axios proxy Konfiguration vs Proxy-Agents

Axios wird mit einem proxy-Objekt geliefert — { host, port, auth } — und es funktioniert gut für einfache HTTP-Ziele. Die Falle ist HTTPS: Wenn das Ziel https:// ist und der Proxy HTTP spricht, kann axios den CONNECT-Tunnel nicht öffnen und Ihre Anfrage hängt entweder oder kommt mit Ihrer echten IP zurück. Die Lösung, auf die sich die Community geeinigt hat, besteht darin, die eingebaute Konfiguration vollständig zu umgehen und axios stattdessen einen Proxy-Agent zu übergeben, dann proxy: false zu setzen, damit die beiden Mechanismen nicht in Konflikt geraten:

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

Zwei Details sparen Stunden. Erstens, verwenden Sie den destrukturierten { HttpsProxyAgent }-Import — neuere Versionen exportieren ihn als benanntes Symbol, und ein Standardimport gibt Ihnen ein Objekt, das beim Erstellen einen Fehler auslöst. Zweitens bleibt das Proxy-URL-Schema http://, selbst wenn der Proxy HTTPS-Verkehr trägt: Das Schema beschreibt, wie Sie den Proxy erreichen, und das TLS zum Ziel läuft innerhalb des Tunnels. Die gleiche Fehlerklasse tritt in Python auf; wenn Sie auch in requests arbeiten, reimen sich die Muster mit unserem ProxyError und SSLError Fix-Guide.

Authentifizierung und Umgebungsvariablen

Authentifizierte Proxies verwenden HTTP-Basic-Anmeldedaten. Mit einem Agenten betten Sie sie in die URL als http://user:pass@host:port ein; wenn das Passwort @, : oder / enthält, kodieren Sie es zuerst mit encodeURIComponent(), oder die URL wird an der falschen Stelle geteilt. Ein 407 Proxy Authentication Required bedeutet, dass die Anmeldedaten abgelehnt wurden oder Ihre Quell-IP nicht auf der Whitelist steht. Axios liest auch HTTP_PROXY, HTTPS_PROXY und NO_PROXY aus der Umgebung — praktisch, um eine Drittanbieter-Bibliothek zu proxyen, ohne deren Code zu berühren — und Sie deaktivieren das, indem Sie proxy: false setzen. Die wichtige Warnung: Der native fetch liest diese Variablen nicht, sodass ein Scraper, der sich auf env-var-Proxying verlässt, direkt geht, sobald Sie von axios zu fetch wechseln.

Proxying des nativen fetch mit undici

Nodes globaler fetch basiert auf undici, und undici ist, wo der Proxy lebt. Sie erstellen einen ProxyAgent und übergeben ihn als nicht-standardisierte dispatcher-Option — dies ist der moderne, abhängigkeitsarme Weg, um fetch zu proxyen, und es behandelt HTTPS CONNECT korrekt direkt aus der Box:

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

Wenn Sie direkt auf undici statt auf global fetch sind, wird derselbe ProxyAgent in request() oder in setGlobalDispatcher() eingesteckt, um jeden fetch im Prozess auf einmal zu proxyen. Dieser globale Schalter mit einem einzigen Aufruf ist der sauberste Weg, um eine gesamte Codebasis durch einen Proxy zu leiten, ohne einen Dispatcher durch jede Funktion zu führen.

SOCKS5-Proxies in Node.js

Weder axios noch undici sprechen SOCKS nativ — geben Sie einen socks5://-String in die axios proxy-Konfiguration ein und Sie erhalten eine protocol mismatch-Assertion. Installieren Sie socks-proxy-agent und verwenden Sie ihn auf die gleiche Weise wie den HTTPS-Agenten, verkabelt in sowohl httpAgent als auch httpsAgent. Bevorzugen Sie socks5h:// über socks5://: das nachfolgende h löst DNS auf der Proxy-Seite auf, was DNS-Lecks stoppt und geo-eingezäunte Hostnamen vom Ausgangsort auflöst. Jeder SOCKS5-Proxy-Plan stellt dasselbe Gateway über HTTP und SOCKS5 bereit, sodass dies ein Schemawechsel ist, kein neuer Kauf:

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

Rotation ohne Proxy-Liste

Das alte Rezept — ein Array von IPs, Math.random() pro Anfrage, die toten entfernen — ist Code, den Sie nicht mehr pflegen. Ein rotierendes Gateway weist bei jeder Anfrage serverseitig eine neue Exit-IP zu, sodass ein Endpunkt wie ein ganzer Pool funktioniert. Durch rotierende Wohnproxies erstreckt sich dieser Pool über 90M+ IPs in über 200 Ländern, und die Schleife unten druckt bei jeder Iteration einen anderen Ursprung ohne Rotationslogik:

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
}

Wenn ein Ablauf mehrere Anfragen umfasst — Anmeldung, in den Warenkorb legen, zur Kasse gehen — bricht die Rotation pro Anfrage die Sitzung. Ein Sticky-Session-Parameter im Proxy-Benutzernamen fixiert eine Exit-IP für ein festgelegtes Fenster und rotiert dann; gleicher Endpunkt, eine Zeichenkettenänderung. Wenn Sie dies auf Tausende gleichzeitiger Anfragen skalieren, verlagern Sie die Arbeit von axios-Schleifen und lesen Sie unseren Leitfaden zur Architektur für groß angelegtes Web-Scraping für Warteschlangen und Budgetierung der Parallelität.

Streaming von Antworten durch einen Proxy

Das Herunterladen von Dateien oder großen JSON-Nutzlasten funktioniert genauso wie jede Anfrage, sobald der Agent angehängt ist — setzen Sie responseType: "stream" und leiten Sie den Body auf die Festplatte. Der Proxy übernimmt den Transfer transparent, sodass ein 200MB-Export niemals im Speicher gepuffert wird:

import fs from "node:fs";

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

Häufig gestellte Fragen

Warum funktioniert mein axios Proxy nicht?

Die häufigste Ursache ist ein HTTPS-Ziel hinter einem HTTP-Proxy: Die eingebaute proxy-Konfiguration von axios kann den CONNECT-Tunnel nicht öffnen und gibt Ihre echte IP zurück oder hängt. Wechseln Sie zu einem Proxy-Agenten — hängen Sie HttpsProxyAgent an httpAgent und httpsAgent an und setzen Sie proxy: false, damit axios aufhört, den Proxy selbst zu handhaben.

Unterstützt axios SOCKS5-Proxies?

Nicht nativ — das Übergeben einer socks5://-URL an die proxy-Konfiguration löst einen Protokoll-Mismatch-Fehler aus. Installieren Sie socks-proxy-agent, erstellen Sie einen SocksProxyAgent und verkabeln Sie ihn in sowohl httpAgent als auch httpsAgent. Verwenden Sie das socks5h://-Schema, damit DNS auf der Proxy-Seite aufgelöst wird, anstatt von Ihrer Maschine zu lecken.

Wie verwende ich einen Proxy mit nativem fetch in Node.js?

Der native fetch hat keine Proxy-Option und ignoriert HTTP_PROXY-Umgebungsvariablen. Erstellen Sie einen undici ProxyAgent und übergeben Sie ihn als dispatcher-Option beim fetch-Aufruf, oder rufen Sie setGlobalDispatcher() einmal auf, um jeden fetch im Prozess zu proxyen. Undici behandelt HTTPS CONNECT korrekt ohne zusätzliche Konfiguration.

Wie setze ich einen axios Proxy mit Umgebungsvariablen?

Exportieren Sie HTTP_PROXY, HTTPS_PROXY und optional NO_PROXY mit vollständigen Proxy-URLs; axios liest sie automatisch. Setzen Sie proxy: false bei einer Anfrage oder Instanz, damit axios die Umgebung ignoriert. Denken Sie daran, dass dies nur axios betrifft — undici und der native fetch werden diese Variablen nicht aufnehmen.

Die ganze Geschichte passt auf eine Karte: axios benötigt einen Agenten und proxy: false, der native fetch benötigt einen undici-Dispatcher, SOCKS benötigt seinen eigenen Agenten, und die Rotation gehört auf das Gateway statt in Ihre Schleife. Richten Sie die Installation richtig ein und die letzte Variable ist die IP-Qualität — ein sauberer Wohn-Exit besteht dort, wo eine markierte Rechenzentrums-IP bei demselben Code ein 403 erhält.

Holen Sie sich Wohnproxies, die bei der ersten Anfrage bestehen