Wie man einen Proxy in Node-Fetch verwendet: Ein praktischer Leitfaden

Node-Fetch verfügt über keinen integrierten Proxy-Parameter. Um Anfragen über einen Proxy zu leiten, übergeben Sie einen Node.js http.Agent (oder https.Agent) an die agent Option bei jedem fetch() Aufruf. Die Community-Pakete https-proxy-agent und socks-proxy-agent implementieren diese Schnittstelle und leiten Ihren Datenverkehr durch den von Ihnen angegebenen Proxy.

Das Fazit: Das einzige Node-Fetch-spezifische Wissen, das du benötigst, ist, dass die agent Option existiert und jeden kompatiblen Agenten akzeptiert. Alles andere – HTTP, HTTPS, SOCKS5, Authentifizierung, TLS-Eigenheiten, Rotation – befindet sich in der Agent-Ebene. Dadurch bleibt Ihr Fetch-Code über alle Anbieter hinweg identisch und Sie können den Transport wechseln, ohne die Geschäftslogik neu schreiben zu müssen.

Sie benötigen eine aktuelle Node.js-LTS-Version. Die node-fetch README gibt eine genaue Mindestversion an, die sich über die Releases hinweg geändert hat; überprüfen Sie diese daher anhand des offiziellen node-fetch Repository ab, bevor Sie Ihre CI-Matrix festlegen. Alles aus einer aktuellen LTS-Reihe ist normalerweise sicher.

Wählen Sie node-fetch Hauptversion bewusst aus. Version 3 ist nur für ESM, was bedeutet, dass du "type": "module" in Ihrer package.json (oder verwenden .mjs Dateien) festlegen und mit import. Version 2 funktioniert weiterhin in CommonJS-Projekten und ist für Proxy-Zwecke austauschbar. Die beiden Versionen verhalten sich weitgehend gleich, daher ist v2 eine durchaus sinnvolle Wahl, wenn Ihre Codebasis noch nicht auf ESM umgestellt ist.

Installieren Sie den Proxy-Agenten zusammen mit Node-Fetch:

# CommonJS friendly
npm install node-fetch@2 https-proxy-agent

# ESM (requires "type": "module" in package.json)
npm install node-fetch https-proxy-agent

Sobald die Pakete installiert sind, ist die Vorgehensweise einfach: Erstellen Sie eine Proxy-URL, übergeben Sie diese an HttpsProxyAgentund übergeben Sie diesen Agenten an fetch(). Die gleiche Agent-Klasse funktioniert unabhängig davon, ob Ihr Ziel http:// oder https://ist, da sie HTTPS mit CONNECT.

// proxy-fetch.js (CommonJS, node-fetch v2)
const fetch = require('node-fetch');
const { HttpsProxyAgent } = require('https-proxy-agent');

async function main() {
  const proxyUrl = `http://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`;
  const agent = new HttpsProxyAgent(proxyUrl);

  const res = await fetch('https://ifconfig.me/all.json', { agent });
  const body = await res.json();
  console.log('Outbound IP:', body.ip_addr);
}

main().catch(console.error);

Ein paar Details, die bei der Bereitstellung stillschweigend eine Rolle spielen:

• Verwenden Sie einen destrukturierten Import ({ HttpsProxyAgent }) für https-proxy-agent v6 und höher. Die Standardform des Exports hat sich über die Hauptversionen hinweg geändert, und ein falscher Import ist eine häufige Ursache für undefined is not a constructor.
• Verwenden Sie denselben Agenten für alle Anfragen, die denselben Proxy ansprechen. Das Erstellen eines neuen Agenten pro Aufruf funktioniert zwar, aber Sie verlieren dabei das Connection-Pooling und müssen jedes Mal einen TLS-Handshake durchführen.
• Rufen Sie zuerst einen bekannten IP-Echo-Endpunkt auf (ifconfig.me, ident.meoder ipinfo.io/json). Wenn die IP-Adresse des Proxys nicht zurückkommt, fahren Sie nicht fort; nichts anderes funktioniert, bis dieser Basisfall erfüllt ist.

Die meisten kostenpflichtigen Proxys erfordern Anmeldedaten. Es ist üblich, diese in der URL mit dem http://USERNAME:PASSWORD@HOST:PORT Form, die https-proxy-agent für Sie parst:

const user = encodeURIComponent(process.env.PROXY_USER);
const pass = encodeURIComponent(process.env.PROXY_PASS);
const proxyUrl = `http://${user}:${pass}@${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`;
const agent = new HttpsProxyAgent(proxyUrl);

Zwei Dinge bereiten hier oft Probleme. Erstens: Das Festschreiben von Anmeldedaten in Quelldateien führt dazu, dass diese über die Git-Historie offengelegt werden; speichere sie in Umgebungsvariablen (oder einem Secrets-Manager) und füge sie zur Laufzeit ein. Zweitens: Sonderzeichen in Passwörtern (@, :, /, #) führen zu einer stillen Beschädigung der URL-Analyse, und Sie erhalten eine irreführende 407 Proxy Authentication Required anstelle eines Parsing-Fehlers. Wenn du Benutzername und Passwort in encodeURIComponent() , wird diese ganze Fehlerklasse beseitigt.

Wenn Ihr Provider Ihnen einen SOCKS5-Endpunkt zur Verfügung stellt, tauschen Sie den Agenten aus. Node-Fetch kümmert sich nicht um das Protokoll; es ruft einfach den Agenten auf, den Sie ihm übergeben. Installieren socks-proxy-agent:

npm install socks-proxy-agent

const fetch = require('node-fetch');
const { SocksProxyAgent } = require('socks-proxy-agent');

// socks5h:// resolves DNS through the proxy; socks5:// resolves locally.
const proxyUrl = `socks5h://${process.env.PROXY_USER}:${process.env.PROXY_PASS}` +
                 `@${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`;
const agent = new SocksProxyAgent(proxyUrl);

fetch('https://ifconfig.me/all.json', { agent })
  .then(r => r.json())
  .then(console.log);

Verwenden Sie beim Scraping vorzugsweise das socks5h:// Schema, da es die DNS-Auflösung über den Proxy weiterleitet. Das einfache socks5:// Schema löst den Hostnamen auf Ihrem Rechner auf, wodurch Ihr echtes DNS preisgegeben wird und der Sinn der Weiterleitung über den Proxy teilweise zunichte gemacht wird.

Einige Proxy-Produkte, insbesondere die „Web-Unblocker“-Dienste vom Typ „Interception“, legen Ihrem Client ihr eigenes TLS-Zertifikat vor und signieren die Antwort vom Upstream neu. Node lehnt diesen Handshake standardmäßig mit UNABLE_TO_VERIFY_LEAF_SIGNATURE oder SELF_SIGNED_CERT_IN_CHAIN.

Die einfache Lösung besteht darin, process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'. Tun Sie das nicht in der Produktion. Es deaktiviert die Zertifikatsüberprüfung für jede ausgehende Anfrage im Prozess, einschließlich derer, die Sie unbedingt verifiziert haben möchten.

Beschränken Sie dies stattdessen auf den Agenten selbst:

const agent = new HttpsProxyAgent(proxyUrl, { rejectUnauthorized: false });

Dadurch bleibt die TLS-Sicherheit des restlichen Teils Ihrer Anwendung erhalten. Der genaue Name der Konstruktoroption und ihre Ausbreitung haben sich über https-proxy-agent Hauptversionen geändert, überprüfen Sie daher bei einem Upgrade die npm-Seite des Pakets und vermeiden Sie dieses Flag gänzlich, wenn Sie stattdessen ein CA-Bundle festlegen können.

Viele Websites nutzen IP-basierte Ratenbegrenzung und Bot-Erkennung, sodass eine einzelne Proxy-IP gedrosselt oder gesperrt wird, sobald Sie skalieren. Die Rotation über einen Pool verteilt die Last und lässt jede Anfrage so aussehen, als käme sie von einem anderen Nutzer. Es gibt zwei Muster, die Sie kennen sollten, um einen Proxy in Node-Fetch in großem Maßstab zu nutzen: eine zufällige Auswahl pro Anfrage und ein deterministischer Round-Robin-Durchlauf. Beide bauen auf dem gleichen Prinzip „ein Agent pro Proxy“ auf, das Sie bereits kennen.

Wenn Ihnen nur die Streuung wichtig ist, greifen Sie zufällig auf den Pool zu und instanziieren Sie pro Aufruf einen neuen Agenten:

const proxies = process.env.PROXY_POOL.split(','); // host:port,host:port,...

function randomAgent() {
  const pick = proxies[Math.floor(Math.random() * proxies.length)];
  return new HttpsProxyAgent(`http://${pick}`);
}

await fetch(targetUrl, { agent: randomAgent() });

Wenn derselbe Proxy mehrere aufeinanderfolgende Anfragen bedient, speichere seinen Agenten in einem Map nach Proxy-URL indiziert, damit die Wiederverwendung der Verbindung gewährleistet ist.

Für reproduzierbares Debugging oder einfaches Round-Robin-Verhalten durchlaufen Sie die Liste mit einem Zähler. Die sequenzielle Rotation erleichtert zudem die Zuordnung von Erfolgskennzahlen pro Proxy, was wichtig ist, sobald Sie nicht mehr funktionierende Proxys aus dem Verkehr ziehen:

let i = 0;
for (const url of urls) {
  const agent = new HttpsProxyAgent(`http://${proxies[i % proxies.length]}`);
  await fetch(url, { agent });
  i++;
}

Produktionsdatenverkehr über öffentliche Proxys scheitert auf interessante Weise: Hänger, halb geöffnete Sockets, vorübergehende ECONNRESET, plötzliche 5xx-Stürme. Eine robuste Konfiguration kombiniert ein Timeout pro Anfrage, eine begrenzte Wiederholungsschleife mit Backoff und einen Circuit Breaker, der einen Proxy nach wiederholten Fehlern aus dem Verkehr zieht. (Mehr zur Rotationsstrategie in unserem ausführlichen Leitfaden zur Rotation von Proxys für Web-Scraping.)

async function fetchWithProxy(url, getAgent, opts = {}) {
  const { tries = 3, timeoutMs = 10_000 } = opts;
  let lastErr;

  for (let attempt = 1; attempt <= tries; attempt++) {
    const ctrl = new AbortController();
    const t = setTimeout(() => ctrl.abort(), timeoutMs);
    try {
      const res = await fetch(url, { agent: getAgent(), signal: ctrl.signal });
      if (res.ok) return res;
      if (res.status === 407 || res.status === 403) throw new Error(`status ${res.status}`);
    } catch (err) {
      lastErr = err;
      const backoff = 2 ** attempt * 250 + Math.random() * 250;
      await new Promise(r => setTimeout(r, backoff));
    } finally {
      clearTimeout(t);
    }
  }
  throw lastErr ?? new Error('exhausted retries');
}

Verfolgen Sie die Fehleranzahl pro Proxy-URL in einem kleinen Objekt, und wenn eine einen Schwellenwert überschreitet (zum Beispiel drei Fehler in einer Minute), entfernen Sie sie aus dem Pool, bis eine Abkühlphase abgelaufen ist. Diese eine Regel ist der Teil, den die meisten Tutorials überspringen, wenn sie erklären, wie man einen Proxy in Node-Fetch verwendet, und sie ist es, die verhindert, dass eine Handvoll toter IPs jeden Wiederholungsversuch vergiftet. Kombinieren Sie dies mit „AbortController“, damit ein hängender Proxy Ihren Worker niemals dauerhaft blockiert.

Vertraue niemals einem Proxy, den du nicht überprüft hast. Der einfachste Test ist ein Diff: Rufe einen IP/Geo-Echo-Endpunkt zweimal auf, einmal mit dem Agent und einmal ohne, und vergleiche die Ergebnisse. Die IP-Adresse und das Land müssen sich ändern.

const direct = await fetch('https://ipinfo.io/json').then(r => r.json());
const proxied = await fetch('https://ipinfo.io/json', { agent }).then(r => r.json());
console.log('direct  :', direct.ip, direct.country);
console.log('proxied :', proxied.ip, proxied.country);

Wenn die beiden Zeilen übereinstimmen, wird Ihr Agent ignoriert, meist aufgrund eines Fehlers bei der Import-Form oder eines falsch geschriebenen Optionsschlüssels. Fügen Sie diese Überprüfung zur Startprobe Ihres Scrapers hinzu, damit eine stillschweigend direkte Bereitstellung lautstark fehlschlägt.

Node 18 enthält eine globale fetch , der von undici unterstützt wird, und viele Teams haben das node-fetch Paket vollständig abgewandt. Der Haken: Das integrierte fetch die agent Option, sodass https-proxy-agent nicht direkt eingebunden werden. Das native Äquivalent ist undicis ProxyAgent, das als globaler Dispatcher festgelegt ist:

import { ProxyAgent, setGlobalDispatcher } from 'undici';

setGlobalDispatcher(new ProxyAgent(process.env.PROXY_URL));

const res = await fetch('https://ifconfig.me/all.json');
console.log(await res.json());

Die undici-Proxy-API hat sich im Laufe der Releases verändert (Authentifizierung in der URL, benutzerdefinierte Header, Dispatcher im Request-Scope), daher sollten Sie die aktuelle undici-Dokumentation prüfen, bevor Sie etwas festlegen. Das mentale Modell entspricht nach wie vor genau der Verwendung eines Proxys in Node-Fetch, nur auf der Dispatcher-Ebene statt pro Anfrage.

Die meisten node-fetch Proxy-Fehler lassen sich in eine kleine Matrix einordnen:

Wenn ein Ziel über mehrere funktionierende Proxys hinweg immer wieder fehlschlägt, liegt der Engpass in der Regel eher im Anti-Bot-Fingerprinting als in der Proxy-Ebene. An diesem Punkt hilft keine noch so sorgfältige Optimierung der Proxy-Nutzung in Node-Fetch; Sie benötigen eine Request-Ebene, die auch das Fingerprinting abdeckt.

Der Mechanismus hinter der Verwendung eines Proxys in Node-Fetch ist eine Möglichkeit: agent. Wählen Sie die richtige Agentenklasse (HttpsProxyAgent für HTTP/HTTPS, SocksProxyAgent für SOCKS5), geben Sie eine korrekt kodierte URL ein, und der Rest besteht aus Rotation, Wiederholungsversuchen und Verifizierung. Von hier aus sind die logischen nächsten Schritte die Einbindung von Rotationslogik und der Vergleich alternativer HTTP-Clients für Node.js.

• Node-Fetch verfügt über keine proxy Option; man bindet die Unterstützung ein, indem man eine Agent (aus https-proxy-agent oder socks-proxy-agent) an das agent Feld fetch().
• Wählen Sie den Major bewusst aus: node-fetch@3 ist nur für ESM und benötigt "type": "module", während node-fetch@2 die CommonJS-kompatible Wahl mit demselben Proxy-Verhalten ist.
• Führen Sie bei Anmeldedaten immer eine URL-Kodierung durch und lesen Sie diese aus Umgebungsvariablen aus. Ein 407 Proxy Authentication Required handelt es sich häufiger um einen Parsing-Fehler als um einen echten Authentifizierungsfehler.
• Produktionsreifer Node-Fetch-Proxy-Code kombiniert AbortController Timeouts, exponentielles Backoff und das Verwerfen eines defekten Proxys nach einigen Fehlern, nicht nur ein try/catch um fetch.
• Auf Node 18+ mit nativem fetchfunktioniert die agent Option funktioniert nicht; verwende undicis ProxyAgent plus setGlobalDispatcher und überprüfen Sie die API-Oberfläche erneut anhand der aktuellen undici-Dokumentation.

Nein. Weder v2 noch v3 von Node-Fetch implementieren eine proxy Option. Der Proxy-Mechanismus ist in beiden Hauptversionen identisch: Installieren Sie https-proxy-agent (oder socks-proxy-agent), erstellen Sie einen Agenten aus Ihrer Proxy-URL und übergeben Sie ihn fetch() über den agent Parameter. Der einzige Unterschied zwischen v2 und v3 ist das Modulsystem: ESM in v3 gegenüber CommonJS in v2.

Ja, und das solltest du auch tun. Die Wiederverwendung eines Agenten pro (Proxy-URL, Zielhost)-Paar ermöglicht es dem zugrunde liegenden Socket-Pool, Verbindungen aufrechtzuerhalten, was bei jeder Anfrage einen TLS-Handshake überflüssig macht und die Latenz unter Last spürbar reduziert. Erstelle nur dann einen neuen Agenten, wenn sich die Proxy-URL selbst ändert, beispielsweise während der Rotation. Speichere sie in einem Map nach Proxy-URL indiziertem Cache, um sowohl die Wiederverwendung als auch die Rotation zu gewährleisten.

HttpProxyAgent leitet einfache http:// Anfragen durch einen Proxy, ohne CONNECT. HttpsProxyAgent eine HTTP-Anfrage CONNECT an den Proxy und führt dann TLS zum Ziel durch – genau das, was Sie für jede https:// URL. In der Praxis HttpsProxyAgent deckt dies beide Protokolle sicher ab und ist die Standardempfehlung. Greifen Sie HttpProxyAgent nur dann auf, wenn Sie einen bestimmten Grund haben und HTTP-only-Endpunkte ansteuern.

Ein 407 bedeutet, dass der Proxy Ihre Anmeldedaten nicht akzeptiert hat, die Ursache liegt jedoch meist vor dem Proxy selbst. Am häufigsten ist ein Sonderzeichen im Passwort, das die URL-Analyse unterbricht. Umschließen Sie beide Felder mit encodeURIComponent und laden Sie sie aus Umgebungsvariablen neu. Überprüfen Sie anschließend noch einmal das von Ihrem Anbieter erwartete Format der Anmeldedaten (manche verlangen ein Sitzungstoken, einen Ländercode oder ein Sitzungspräfix im Benutzernamen).

Die native fetch in Node 18+ verwendet undici, das die agent Option ignoriert. Installieren undici, erstellen Sie eine ProxyAgent aus Ihrer Proxy-URL und registrieren Sie es bei setGlobalDispatcher. Danach werden alle einfachen fetch() wird ohne weitere Codeänderungen über den Proxy geleitet. Die undici-API hat sich im Laufe der Releases weiterentwickelt, überprüfen Sie daher vor dem Fixieren die aktuellen Optionsnamen anhand der undici-Dokumentation.

Sobald Sie die agent Option verinnerlicht haben, ist jedes Rezept in diesem Leitfaden eine kleine Variation derselben Idee. HTTP, HTTPS und SOCKS5 teilen sich eine Abruf-Signatur; die Authentifizierung ist korrekt durchgeführte URL-Kodierung; Rotation, Wiederholungsversuche und das Überspringen von toten Proxys befinden sich in einem dünnen Wrapper um fetch(); und die Node 18+ undici-Route ist dasselbe mentale Modell, übersetzt in einen globalen Dispatcher.

Unterschätzen Sie die operative Ebene nicht. Kostenlose Proxys sind in der Produktion nutzlos: eine schlechte IP-Reputation, hohe Ausfallzeiten und unvorhersehbares TLS-Verhalten werden Ihr Fehlerbudget aufzehren. Ein sauberer Pool aus privaten oder Rechenzentrums-IPs, zusammen mit dem zuvor erwähnten Wrapper für Timeouts und Wiederholungsversuche, macht aus einem Snippet einen einsatzfähigen Scraper.

Wenn Sie die Proxy-Infrastruktur lieber nicht selbst betreiben möchten, übernimmt die Scraper-API von WebScrapingAPI die Proxy-Rotation, Anti-Bot-Maßnahmen und Wiederholungsversuche hinter einem einzigen Endpunkt, sodass Sie Ihren node-fetch Code beibehalten und die Anforderungsschicht austauschen. Von hier aus sind die logischen nächsten Schritte die Schichtung der Rotationsstrategie und die Auswahl des richtigen Node.js-HTTP-Clients für Ihre Arbeitslast – beides Themen, die in unseren Begleitleitfäden ausführlich behandelt werden.