Leitfaden
Proxy mit Playwright und Puppeteer: richtige Einrichtung für die Browser-Automatisierung
In Playwright legen Sie den Proxy über das proxy-Objekt in launch oder newContext fest, in Puppeteer über --proxy-server oder createBrowserContext zusammen mit page.authenticate. Eigene IP pro Context, SOCKS5-Grenze bei Passwörtern, Sticky-Sitzungen, Traffic sparen und eine Fehlertabelle.
Das Wichtigste in Kürze
- In Playwright übergeben Sie den Proxy an chromium.launch() oder browser.newContext() als Objekt proxy: { server, username, password }; da das Passwort in einem eigenen Feld steht, ist keine Prozentkodierung nötig.
- In Puppeteer setzen Sie die Proxy-Adresse über das Argument --proxy-server oder mit createBrowserContext({ proxyServer }); Benutzername und Passwort übergeben Sie auf jeder Seite vor page.goto() mit page.authenticate().
- Chromium unterstützt keinen SOCKS5-Proxy mit Benutzername und Passwort: Playwright meldet einen Startfehler, Puppeteer liefert ERR_NO_SUPPORTED_PROXIES. Die Lösung ist die HTTP-Adresse des Pakets oder eine lokale Brücke mit proxy-chain.
- Puppeteer wirft bei falschem Proxy-Passwort keinen Fehler, page.goto() liefert eine Antwort mit Status 407; prüfen Sie deshalb den Wert status() der Antwort.
- Bei Sticky-Sitzungen hält ein eigener Context pro Session-ID Cookies und Ausgangs-IP in derselben Einheit; bei Paketen mit Abrechnung pro GB senkt das Blockieren von Bildern den Traffic.
In Playwright wird der Proxy über das Objekt proxy: { server, username, password } festgelegt, das Sie an chromium.launch() oder browser.newContext() übergeben. In Puppeteer erhält Chrome die Adresse über das Argument --proxy-server oder über createBrowserContext({ proxyServer }), Benutzername und Passwort setzen Sie mit page.authenticate(). In beiden Tools unterstützt Chromium keinen SOCKS5-Proxy mit Benutzername und Passwort; in diesem Fall nutzen Sie die HTTP-Adresse des Pakets oder eine lokale Brücke.
In der Browser-Automatisierung funktioniert die Proxy-Einstellung anders als bei HTTP-Clients wie requests oder fetch. Jedes Bild, jedes Script und jeder API-Aufruf, den die Seite lädt, geht über denselben Proxy hinaus, und die Authentifizierung übernimmt der Browser selbst. Die Beispiele verwenden die WeProxy-Gateway-Adresse gw.weproxy.com.tr:8989. USER und PASSWORD sind Ihre Zugangsdaten aus dem Kundenpanel. Alle Beispiele liefen mit Playwright 1.65, Puppeteer 25 und Chrome 158 gegen einen lokalen Test-Proxy.
Wie schreibt man die Proxy-Adresse in Playwright und Puppeteer?
Beide Tools erwarten den Proxy-Server im Format schema://host:port. Auch wenn die Zielseite HTTPS nutzt, beginnt die Adresse eines HTTP-Proxys mit http://; der Browser schickt ein CONNECT an den Proxy und baut die TLS-Verbindung innerhalb dieses Tunnels auf. Eine ohne Schema geschriebene Adresse wie gw.weproxy.com.tr:8989 behandelt Playwright als HTTP-Proxy.
Schreiben Sie Benutzername und Passwort nicht in die Adresse. Playwright nimmt sie in eigenen Feldern des proxy-Objekts entgegen, in Puppeteer übergeben Sie sie mit page.authenticate(). Deshalb ist keine Prozentkodierung nötig, auch wenn das Passwort @ oder : enthält; im Test-Proxy funktionierte das Passwort p@ss:word in beiden Tools unkodiert. Ein Passwort in der Kommandozeile taucht außerdem in der Prozessliste des Systems auf.
Legen Sie die Zugangsdaten in Umgebungsvariablen ab, statt sie in den Code zu schreiben:
export WEPROXY_USERNAME="USER"
export WEPROXY_PASSWORD="PASSWORD"
Haben Sie im Panel eine Liste im Format ip:port:user:pass erhalten, hilft der Proxy-Format-Konverter beim Zerlegen der Zeilen. Details zu den Formaten stehen im Leitfaden zu Proxy-Formaten.
Wie nutzt man einen Proxy in Playwright?
Am einfachsten geben Sie den Proxy beim Start des Browsers an. Alle Contexts und Seiten dieses Browsers gehen dann über denselben Proxy hinaus:
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const page = await browser.newPage();
await page.goto('https://api.ipify.org?format=json');
console.log(await page.textContent('body')); // {"ip":"<Ausgangs-IP des Proxys>"}
await browser.close();
In Python übergeben Sie dieselben Felder als Dictionary:
import os
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(proxy={
"server": "http://gw.weproxy.com.tr:8989",
"username": os.environ["WEPROXY_USERNAME"],
"password": os.environ["WEPROXY_PASSWORD"],
})
page = browser.new_page()
page.goto("https://api.ipify.org?format=json")
print(page.text_content("body"))
browser.close()
Sollen bestimmte Adressen nicht über den Proxy laufen, tragen Sie kommagetrennte Domains im Feld bypass ein, zum Beispiel bypass: 'localhost, .internal.example'. Das ist praktisch für lokale Dienste in der Testumgebung. Wenn Sie in Python Anfragen außerhalb des Browsers senden müssen, finden Sie Beispiele für requests und httpx im Artikel Proxy in Python nutzen.
Wie gibt man in Playwright jedem Context einen eigenen Proxy?
Ein Context ist in Playwright ein separates Browserprofil mit eigenen Cookies und eigenem Speicher. Übergeben Sie den Proxy an browser.newContext(), können Sie mit einem einzigen Browserprozess mehrere Ausgangs-IPs nutzen:
import { chromium } from 'playwright';
const browser = await chromium.launch();
const proxied = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const direct = await browser.newContext();
const p1 = await proxied.newPage();
const p2 = await direct.newPage();
await p1.goto('https://api.ipify.org');
await p2.goto('https://api.ipify.org');
console.log(await p1.textContent('body'), await p2.textContent('body'));
await browser.close();
Im Test liefen alle Anfragen des Contexts mit Proxy über den Proxy, der zweite Context verband sich direkt. In älteren Playwright-Versionen musste man unter Windows für einen Context-Proxy zusätzlich einen Platzhalter-Proxy an launch übergeben; in Playwright 1.65 ist das nicht mehr nötig. Der Proxy des Contexts gilt auch für API-Anfragen über context.request. Um einen JSON-Endpunkt ohne Seitenaufruf abzufragen, brauchen Sie also keinen separaten HTTP-Client.
Wie nutzt man in Puppeteer einen Proxy mit Benutzername und Passwort?
Puppeteer bekommt den Proxy über das Chrome-Argument --proxy-server. Die Zugangsdaten setzen Sie auf jeder Seite mit page.authenticate(), und dieser Aufruf muss vor page.goto() stehen:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://gw.weproxy.com.tr:8989'],
});
try {
const page = await browser.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
const res = await page.goto('https://api.ipify.org?format=json');
if (res.status() === 407) throw new Error('Proxy-Zugangsdaten abgelehnt');
console.log(await page.evaluate(() => document.body.innerText));
} finally {
await browser.close();
}
Im Test warf page.goto() bei falschem Passwort keinen Fehler, sondern lieferte eine Antwort mit dem Statuscode 407. Ein Script ohne status()-Prüfung speichert dann womöglich die Fehlerseite des Proxys als Daten. Laut Puppeteer-Dokumentation schaltet page.authenticate() im Hintergrund das Abfangen von Anfragen (Request Interception) ein; bei vielen Seiten kostet das etwas Geschwindigkeit.
Bei Paketen, deren Proxy mit IP-Whitelist arbeitet, ist page.authenticate() nicht nötig; die Ausgangs-IP des Rechners, auf dem der Code läuft, muss dann im Panel hinterlegt sein. Welche Methode bei welchem Produkt gilt, zeigt eine Tabelle im Leitfaden zur Proxy-Authentifizierung. Die Einrichtungsschritte in Kurzform finden Sie auf der Seite Puppeteer-Integration.
Wie gibt man in Puppeteer jedem Context einen anderen Proxy?
--proxy-server gilt für den gesamten Browser. In aktuellen Puppeteer-Versionen nimmt browser.createBrowserContext() die Optionen proxyServer und proxyBypassList entgegen; so kann jeder Context innerhalb eines einzigen Chrome-Prozesses einen anderen Proxy nutzen:
const browser = await puppeteer.launch();
const ctx = await browser.createBrowserContext({
proxyServer: 'http://gw.weproxy.com.tr:8989',
proxyBypassList: ['localhost'],
});
const page = await ctx.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
await page.goto('https://api.ipify.org');
Da die Zugangsdaten auf Seitenebene und nicht auf Context-Ebene gesetzt werden, wiederholen Sie page.authenticate() für jede neue Seite, die Sie im Context öffnen. Fehlt diese Option in einer älteren Puppeteer-Version, brauchen Sie für jeden Proxy einen eigenen puppeteer.launch()-Prozess.
Wie nutzt man einen SOCKS5-Proxy in der Browser-Automatisierung?
Chromium unterstützt bei SOCKS5-Proxys keine Authentifizierung mit Benutzername und Passwort. Playwright startet den Browser in diesem Fall gar nicht erst und meldet den Fehler Browser does not support socks5 proxy authentication. Schreiben Sie in Puppeteer die Zugangsdaten im Format --proxy-server=socks5://user:pass@host:port, lädt die Seite nicht und bricht mit net::ERR_NO_SUPPORTED_PROXIES ab. Ein SOCKS5-Proxy ohne Authentifizierung funktioniert in beiden Tools problemlos.
Bietet Ihr Paket auch HTTP an, verwenden Sie im Browser die HTTP-Adresse; für den Seiten-Traffic hat SOCKS5 keinen Vorteil. Ist SOCKS5 Pflicht, öffnen Sie auf dem Rechner eine lokale HTTP-Brücke ohne Authentifizierung. Das Paket proxy-chain erledigt das in einer Zeile:
import puppeteer from 'puppeteer';
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain';
const user = encodeURIComponent(process.env.WEPROXY_USERNAME);
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);
const local = await anonymizeProxy(`socks5://${user}:${pass}@gw.weproxy.com.tr:8989`);
// local: http://127.0.0.1:<port>
const browser = await puppeteer.launch({ args: [`--proxy-server=${local}`] });
const page = await browser.newPage();
await page.goto('https://api.ipify.org');
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();
await closeAnonymizedProxy(local, true);
Weil die Brückenadresse eine URL ist, wird das Passwort hier mit encodeURIComponent kodiert. Die lokale Brücke lauscht nur auf 127.0.0.1; in Playwright lässt sie sich genauso als server: local einsetzen. Die Unterschiede zwischen HTTP und SOCKS5 erklärt der Artikel HTTP vs. SOCKS5. Der Mobile 5G Proxy mit echter SIM funktioniert nur mit HTTP, daher braucht dieses Produkt keine Brücke.
Playwright und Puppeteer im Vergleich: Proxy-Einstellungen
| Merkmal | Playwright | Puppeteer |
|---|---|---|
| Proxy für den ganzen Browser | launch({ proxy: { server } }) | args: ['--proxy-server=...'] |
| Proxy pro Context | newContext({ proxy }) | createBrowserContext({ proxyServer }) |
| Benutzername und Passwort | proxy.username, proxy.password | page.authenticate() auf jeder Seite |
| Adressen außerhalb des Proxys | bypass: 'a.com, .b.com' | proxyBypassList oder --proxy-bypass-list |
| SOCKS5 mit Passwort | Nicht unterstützt, Startfehler | Nicht unterstützt, ERR_NO_SUPPORTED_PROXIES |
| Verhalten bei falschem Passwort | page.goto() wirft einen Fehler | page.goto() liefert eine 407-Antwort |
| Sprachunterstützung | JavaScript, Python, Java, .NET | JavaScript |
Da die Zugangsdaten in Playwright Teil der Proxy-Einstellung sind, bleibt der Code bei Aufgaben mit vielen Contexts kürzer. Haben Sie ein Projekt bereits mit Puppeteer aufgebaut, müssen Sie das Tool nicht wechseln; createBrowserContext bietet dieselbe Flexibilität.
Welcher Proxy-Typ eignet sich für die Browser-Automatisierung?
Ein Browser erzeugt deutlich mehr Traffic als ein HTTP-Client. Eine einzelne Produktseite kann mit Bildern, Schriften und Scripts mehrere Megabyte umfassen. Deshalb richtet sich die Wahl des Produkts sowohl nach dem Ziel als auch nach dem Abrechnungsmodell:
| Aufgabe | Passendes Produkt | Grund |
|---|---|---|
| Scraping über viele Seiten, SERP- und Preisprüfung | Rotating Residential IPv4 | Sticky- und Rotating-Sitzung, Länder- und Städte-Targeting, HTTP und SOCKS5 |
| Hohes Volumen, ungeschützte Ziele | Rotating Datacenter IPv4 | Abrechnung pro GB, Sticky-Sitzung von 1–5 Minuten |
| Lange Sitzungen mit Login, feste IP pro Konto | ISP Proxy oder Static Residential IPv4 | IP bleibt während der Laufzeit gleich; bei Static Residential ohne Traffic-Limit |
| Mobile Ansicht und App-Tests | Mobile 5G Proxy | Echte SIM, nur HTTP und Benutzername/Passwort |
Bei Produkten mit Abrechnung pro GB senkt das Blockieren von Bildern und Medien den Traffic spürbar. In Playwright genügt dafür eine route auf Context-Ebene:
await context.route('**/*', (route) => {
const type = route.request().resourceType();
return ['image', 'media', 'font'].includes(type) ? route.abort() : route.continue();
});
Beim Auslesen von Preisen oder Lagerbeständen spielt die Darstellung der Seite keine Rolle; meist reichen Text und JSON-LD-Daten. Wie man die Preisbeobachtung in Aktionszeiträumen aufbaut, beschreibt der Leitfaden zur Preisbeobachtung am Black Friday ausführlich. IP-Typ und Sitzungswahl für Scraping-Aufgaben erklärt auch die Seite Web Scraping.
Wie ordnet man Sticky-Sitzungen den Browser-Contexts zu?
Bei einem Rotating-Gateway bleibt die Proxy-Adresse gleich, während die Ausgangs-IP aus dem Pool wechselt. Bei Login, Warenkorb oder mehrstufigen Formularen müssen dagegen alle Schritte über dieselbe IP laufen. In den Residential-Pools von WeProxy wird dafür eine Session-ID an den Benutzernamen angehängt. Das Format des Benutzernamens und die Sitzungsdauer je Produkt entnehmen Sie dem Panel.
In der Browser-Automatisierung ordnen Sie am saubersten jeder Sitzung einen eigenen Context zu. So bleiben Cookies, Speicher und Ausgangs-IP in derselben Einheit:
import { chromium } from 'playwright';
// Benutzernamen werden aus dem Panel kopiert; jedes Profil trägt seine eigene Session-ID.
const PROFILES = ['USER_WITH_SESSION_1', 'USER_WITH_SESSION_2'];
const browser = await chromium.launch();
for (const username of PROFILES) {
const context = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username,
password: process.env.WEPROXY_PASSWORD,
},
locale: 'de-DE',
timezoneId: 'Europe/Berlin',
});
const page = await context.newPage();
await page.goto('https://api.ipify.org');
console.log(username, await page.textContent('body'));
await context.close();
}
await browser.close();
Mit locale und timezoneId zeigt die Website Sprache und Datumsformat passend zum Land des Proxys an; eine Seite, die mit deutscher IP geöffnet wird, zeigt dann kein englisches Datum und keine fremde Währung. Zwei Contexts sollten nie dieselbe Session-ID teilen. Welche Aufgabe Sticky und welche Rotating braucht, zeigt der Leitfaden Sticky oder Rotating mit einer Szenario-Tabelle. Dieselben Abstimmungen für Antidetect-Browser beschreibt der Artikel Antidetect-Browser + Proxy.
Wie prüft man, ob der Proxy funktioniert, und was bedeuten die Fehler?
Am schnellsten testen Sie, indem Sie im selben Browser einen Context mit und einen ohne Proxy öffnen und das Ergebnis von api.ipify.org vergleichen. Sind beide Werte gleich, kommt die Proxy-Einstellung nicht beim Browser an. Land und Netz der Ausgangs-IP zeigt das My-IP-Tool. Um den Proxy unabhängig vom Code zu testen, nutzen Sie den Proxy-Checker; funktioniert ein Proxy dort, aber nicht im Browser, liegt das Problem in der Script-Einstellung.
Fehler mit Chrome 158 im Test-Proxy:
| Situation | Playwright | Puppeteer |
|---|---|---|
| Keine Zugangsdaten angegeben | net::ERR_INVALID_AUTH_CREDENTIALS | net::ERR_INVALID_AUTH_CREDENTIALS |
| Falsches Passwort | net::ERR_HTTP_RESPONSE_CODE_FAILURE | Kein Fehler, Antwortstatus 407 |
| Keine Verbindung zum Proxy | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
HTTP-Proxy mit https:// geschrieben | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
| SOCKS5 mit Passwort | Browser does not support socks5 proxy authentication | net::ERR_NO_SUPPORTED_PROXIES |
Bei Authentifizierungsfehlern ändert ein erneuter Versuch nichts am Ergebnis; prüfen Sie zuerst, ob das Paket aktiv ist und der Benutzername mit dem im Panel übereinstimmt. Kommt ERR_PROXY_CONNECTION_FAILED dauerhaft, blockiert womöglich Ihr Netzwerk oder Ihr Cloud-Anbieter ausgehende Verbindungen auf Port 8989. Aus welcher Schicht Codes wie 403 und 429 stammen, die nach dem Aufbau der Proxy-Verbindung vom Ziel kommen, erklärt der Überblick über Proxy-Fehlercodes. Bei diesen Codes reichen meist Wiederholungen mit wachsendem Abstand und eine geringere Parallelität.
Compliance und Sicherheit in der Browser-Automatisierung
Wenn Sie eine Automatisierung zur Datenerhebung schreiben, halten Sie sich an die robots.txt des Ziels (RFC 9309) und an dessen Nutzungsbedingungen, auch wenn die Anfragen über einen Proxy laufen, und halten Sie die Zahl paralleler Contexts auf einem Niveau, das die Website verkraftet. Verarbeiten Sie personenbezogene Daten, gelten die Pflichten aus der DSGVO unabhängig vom Proxy. Welche Nutzungen bei WeProxy-Diensten erlaubt sind und welche nicht, steht auf der Seite Acceptable Use.
Screenshots und Trace-Dateien enthalten Seiteninhalte und manchmal auch Sitzungs-Cookies; prüfen Sie sie, bevor Sie sie weitergeben. Geben Sie das Proxy-Passwort nicht in Logs oder Fehlermeldungen aus. Für Anfragen außerhalb des Browsers funktionieren die undici- und axios-Beispiele aus dem Artikel Proxy in Node.js nutzen mit denselben Proxy-Daten wie Playwright. Ausführliche API-Optionen finden Sie in der Playwright-Proxy-Dokumentation und in der Puppeteer-Dokumentation zu BrowserContextOptions.
Häufige Fragen
Wie richtet man in Playwright einen Proxy mit Benutzername und Passwort ein?
Übergeben Sie an chromium.launch() oder browser.newContext() ein proxy-Objekt: Im Feld server steht die Adresse http://host:port, in username und password Ihre Daten aus dem Panel. Da die Zugangsdaten nicht in der Adresse stehen, ist keine Kodierung nötig, auch wenn das Passwort @ oder : enthält. In Python übergeben Sie dieselben Felder als Dictionary in p.chromium.launch(proxy={...}). Alle Contexts und Seiten dieses Browsers nutzen denselben Proxy.
Wie funktioniert die Proxy-Authentifizierung in Puppeteer?
Starten Sie den Browser mit dem Argument --proxy-server=http://host:port und rufen Sie auf jeder neuen Seite vor page.goto() page.authenticate({ username, password }) auf. Hängen Sie die Zugangsdaten nicht an die --proxy-server-Adresse; Chromium unterstützt dieses Format nicht, und das Passwort erscheint in der Prozessliste. Bei falschem Passwort wirft Puppeteer keinen Fehler, sondern liefert eine Antwort mit Status 407; prüfen Sie daher status() im Ergebnis von page.goto().
Können verschiedene Seiten in einem Browser unterschiedliche Proxys nutzen?
Ja, auf Context-Ebene. In Playwright bekommt jeder Aufruf von browser.newContext() ein eigenes proxy-Objekt. In aktuellen Puppeteer-Versionen erledigt browser.createBrowserContext({ proxyServer }) dasselbe, die Zugangsdaten setzen Sie weiterhin mit page.authenticate(). Seiten im selben Context teilen sich den Proxy; wenn jede Seite einen eigenen Proxy braucht, öffnen Sie für jede Seite einen eigenen Context.
Warum meldet Playwright „Browser does not support socks5 proxy authentication“?
Chromium unterstützt bei SOCKS5-Proxys keine Authentifizierung mit Benutzername und Passwort; Playwright erkennt das, bevor der Browser startet. Bietet Ihr Paket auch HTTP an, verwenden Sie im Browser die HTTP-Adresse. Ist SOCKS5 Pflicht, öffnen Sie mit der Funktion anonymizeProxy aus dem Paket proxy-chain eine HTTP-Brücke ohne Authentifizierung auf 127.0.0.1 und geben dem Browser diese Adresse.
Wie reduziert man den Proxy-Traffic in der Browser-Automatisierung?
Bilder, Schriften und Videos machen den Großteil des Traffics aus. Brechen Sie in Playwright mit context.route() Anfragen der Typen image, media und font ab; in Puppeteer geht das mit page.setRequestInterception(true). Wenn Sie Preise, Lagerbestände oder Texte auslesen, brauchen Sie die Darstellung der Seite nicht. Bei Rotating-Paketen mit Abrechnung pro GB senkt diese Einstellung den Verbrauch spürbar.









