Integration von Proxys mit Puppeteer und Playwright: Umfassender Leitfaden mit Codebeispielen

Puppeteer und Playwright sind beliebte Tools zur Automatisierung von Browsern und Web-Scraping. Bei der Arbeit mit großen Mengen an Anfragen oder beim Scraping geschützter Websites wird die Verwendung von Proxys entscheidend, um IP-Sperren zu vermeiden. In diesem Leitfaden werden wir alle Möglichkeiten zur Integration von Proxys in beide Tools untersuchen, von der grundlegenden Einrichtung bis hin zu fortgeschrittenen Szenarien mit Rotation und Fehlerbehandlung.

Grundlagen der Proxy-Nutzung in Headless-Browsern

Puppeteer und Playwright steuern echte Browser (Chromium, Firefox, WebKit) über das DevTools-Protokoll. Das bedeutet, dass der Proxy auf der Ebene des Browserstarts und nicht auf der Ebene einzelner Anfragen konfiguriert wird. Beide Tools unterstützen HTTP-, HTTPS- und SOCKS5-Proxys, haben jedoch unterschiedliche APIs für deren Einrichtung.

Wichtige Unterschiede zu herkömmlichen HTTP-Bibliotheken (axios, fetch):

• Proxy wird beim Start des Browsers festgelegt — der Proxy kann während einer Browsersitzung nicht dynamisch geändert werden
• Unterstützung von JavaScript und Rendering — der Proxy wird auf alle Ressourcen der Seite angewendet (Bilder, Skripte, XHR)
• Automatische Behandlung von Weiterleitungen und Cookies — der Browser verhält sich wie ein echter Benutzer
• Fingerprinting — selbst mit Proxys können Websites die Automatisierung anhand der Browsermerkmale erkennen

Proxy-Einrichtung in Puppeteer

Puppeteer ist eine Bibliothek von Google zur Steuerung von Chrome/Chromium. Der Proxy wird über die Startargumente des Browsers mit dem Flag --proxy-server konfiguriert.

Grundlegende Einrichtung von HTTP/HTTPS-Proxys

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    args: [
      '--proxy-server=http://proxy.example.com:8080'
    ]
  });

  const page = await browser.newPage();
  
  // Überprüfung der IP-Adresse
  await page.goto('https://api.ipify.org?format=json');
  const content = await page.content();
  console.log('Aktuelle IP:', content);

  await browser.close();
})();

Dieser Code startet den Browser über einen Proxy-Server. Alle HTTP- und HTTPS-Anfragen werden über den angegebenen Proxy geleitet. Zur Überprüfung der Funktionsfähigkeit wird der Dienst ipify verwendet, der die externe IP-Adresse zurückgibt.

Einrichtung von SOCKS5-Proxys

const browser = await puppeteer.launch({
  headless: true,
  args: [
    '--proxy-server=socks5://proxy.example.com:1080'
  ]
});

// Der restliche Code ist ähnlich

SOCKS5-Proxys arbeiten auf einer niedrigeren Ebene und unterstützen UDP-Verkehr, was für einige Webanwendungen nützlich sein kann. Die Syntax ist identisch mit der von HTTP-Proxys, nur das Protokoll in der URL ändert sich.

Verwendung von Proxys für bestimmte Domains

const browser = await puppeteer.launch({
  args: [
    '--proxy-server=http://proxy1.example.com:8080',
    '--proxy-bypass-list=localhost;127.0.0.1;*.internal.com'
  ]
});

// Lokale Anfragen und Anfragen an *.internal.com gehen direkt
// Alle anderen über den Proxy

Das Flag --proxy-bypass-list ermöglicht es, bestimmte Domains von der Proxy-Nutzung auszuschließen. Dies ist nützlich, wenn direkte und proxybasierte Anfragen kombiniert werden müssen.

Proxy-Einrichtung in Playwright

Playwright ist eine modernere Bibliothek von Microsoft, die Chromium, Firefox und WebKit unterstützt. Der Proxy wird über ein Konfigurationsobjekt eingerichtet, was die API verständlicher und typisierter macht.

Grundlegende Proxy-Einrichtung

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://proxy.example.com:8080'
    }
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  
  await page.goto('https://api.ipify.org?format=json');
  const ip = await page.textContent('body');
  console.log('IP über Proxy:', ip);

  await browser.close();
})();

Playwright verwendet das Objekt proxy anstelle von Befehlszeilenargumenten. Dies sorgt für eine bessere Typisierung in TypeScript und einen saubereren Code.

Proxy-Einrichtung auf Kontext-Ebene

const browser = await chromium.launch();

// Kontext 1 - mit Proxy
const context1 = await browser.newContext({
  proxy: {
    server: 'http://proxy1.example.com:8080'
  }
});

// Kontext 2 - mit einem anderen Proxy
const context2 = await browser.newContext({
  proxy: {
    server: 'http://proxy2.example.com:8080'
  }
});

const page1 = await context1.newPage();
const page2 = await context2.newPage();

// Jede Seite verwendet ihren eigenen Proxy!

Ein entscheidender Vorteil von Playwright ist die Möglichkeit, mehrere Browserkontexte mit unterschiedlichen Proxys innerhalb eines Prozesses zu erstellen. Dies spart Ressourcen bei der Arbeit mit vielen IP-Adressen.

Ausschluss von Domains von der Proxy-Nutzung

const browser = await chromium.launch({
  proxy: {
    server: 'http://proxy.example.com:8080',
    bypass: 'localhost,127.0.0.1,*.internal.com'
  }
});

// Anfragen an localhost und *.internal.com gehen direkt

Authentifizierung mit Benutzername und Passwort

Die meisten kommerziellen Proxys erfordern eine Authentifizierung. Beide Tools unterstützen die Autorisierung, implementieren sie jedoch unterschiedlich.

Authentifizierung in Puppeteer

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://proxy.example.com:8080']
});

const page = await browser.newPage();

// Anmeldedaten für den Proxy festlegen
await page.authenticate({
  username: 'your_username',
  password: 'your_password'
});

await page.goto('https://httpbin.org/ip');
const content = await page.content();
console.log(content);

Die Methode page.authenticate() legt die Anmeldedaten für alle nachfolgenden Anfragen auf dieser Seite fest. Es ist wichtig, sie VOR dem ersten page.goto() aufzurufen.

Authentifizierung in Playwright

const browser = await chromium.launch({
  proxy: {
    server: 'http://proxy.example.com:8080',
    username: 'your_username',
    password: 'your_password'
  }
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip');

Playwright ermöglicht es, die Anmeldedaten direkt im Proxy-Konfigurationsobjekt anzugeben — das ist bequemer und sicherer, da es keine zusätzlichen Methodenaufrufe erfordert.

Alternative Methode: Anmeldedaten in der URL

// Funktioniert in beiden Frameworks
const proxyUrl = 'http://username:password@proxy.example.com:8080';

// Puppeteer
const browser = await puppeteer.launch({
  args: [`--proxy-server=${proxyUrl}`]
});

// Playwright
const browser = await chromium.launch({
  proxy: { server: proxyUrl }
});

Diese Methode funktioniert, wird jedoch nicht für die Produktion empfohlen — Anmeldedaten könnten in Logs landen. Verwenden Sie Umgebungsvariablen zur Speicherung sensibler Daten.

Proxy-Rotation und IP-Pool-Management

Für großflächiges Scraping müssen IP-Adressen regelmäßig gewechselt werden. Da der Proxy beim Start des Browsers festgelegt wird, erfordert die Rotation einen Neustart der Browsersitzung.

Einfache Rotation mit einem Proxy-Array (Puppeteer)

const puppeteer = require('puppeteer');

const proxyList = [
  'http://user1:pass1@proxy1.example.com:8080',
  'http://user2:pass2@proxy2.example.com:8080',
  'http://user3:pass3@proxy3.example.com:8080'
];

async function scrapeWithRotation(urls) {
  for (let i = 0; i < urls.length; i++) {
    const proxyUrl = proxyList[i % proxyList.length];
    
    const browser = await puppeteer.launch({
      args: [`--proxy-server=${proxyUrl}`]
    });

    try {
      const page = await browser.newPage();
      await page.goto(urls[i], { waitUntil: 'networkidle0' });
      
      const data = await page.evaluate(() => {
        return {
          title: document.title,
          url: window.location.href
        };
      });
      
      console.log(`URL ${i + 1}:`, data);
    } catch (error) {
      console.error(`Fehler bei ${urls[i]}:`, error.message);
    } finally {
      await browser.close();
    }
  }
}

const urlsToScrape = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3',
  'https://example.com/page4'
];

scrapeWithRotation(urlsToScrape);

Dieser Code durchläuft zyklisch die Proxys aus der Liste und startet einen neuen Browser für jede URL. Die Methode i % proxyList.length sorgt für eine zyklische Rotation.

Rotation mit einem Kontext-Pool (Playwright)

const { chromium } = require('playwright');

const proxyList = [
  { server: 'http://proxy1.example.com:8080', username: 'user1', password: 'pass1' },
  { server: 'http://proxy2.example.com:8080', username: 'user2', password: 'pass2' },
  { server: 'http://proxy3.example.com:8080', username: 'user3', password: 'pass3' }
];

async function scrapeWithContextPool(urls) {
  const browser = await chromium.launch();
  
  // Erstellen eines Pools von Kontexten mit unterschiedlichen Proxys
  const contexts = await Promise.all(
    proxyList.map(proxy => browser.newContext({ proxy }))
  );

  for (let i = 0; i < urls.length; i++) {
    const context = contexts[i % contexts.length];
    const page = await context.newPage();
    
    try {
      await page.goto(urls[i], { waitUntil: 'networkidle' });
      const title = await page.title();
      console.log(`URL ${i + 1} (Proxy ${i % contexts.length}):`, title);
    } catch (error) {
      console.error(`Fehler bei ${urls[i]}:`, error.message);
    } finally {
      await page.close();
    }
  }

  await browser.close();
}

const urls = [
  'https://example.com/page1',
  'https://example.com/page2',
  'https://example.com/page3'
];

scrapeWithContextPool(urls);

Playwright ermöglicht es, mehrere Kontexte in einem Browser zu erstellen, jeder mit seinem eigenen Proxy. Dies spart Speicher und Startzeit im Vergleich zum vollständigen Neustart des Browsers.

Intelligente Rotation mit Fehlerverfolgung

class ProxyRotator {
  constructor(proxyList) {
    this.proxyList = proxyList;
    this.currentIndex = 0;
    this.failedProxies = new Set();
  }

  getNext() {
    const availableProxies = this.proxyList.filter(
      (_, index) => !this.failedProxies.has(index)
    );

    if (availableProxies.length === 0) {
      throw new Error('Alle Proxys sind nicht verfügbar');
    }

    const proxy = this.proxyList[this.currentIndex];
    this.currentIndex = (this.currentIndex + 1) % this.proxyList.length;
    
    return { proxy, index: this.currentIndex - 1 };
  }

  markFailed(index) {
    this.failedProxies.add(index);
    console.log(`Proxy ${index} als nicht verfügbar markiert`);
  }

  resetFailed() {
    this.failedProxies.clear();
  }
}

// Verwendung
const rotator = new ProxyRotator(proxyList);

async function scrapeWithSmartRotation(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const { proxy, index } = rotator.getNext();
    
    const browser = await chromium.launch({ proxy });
    const page = await browser.newPage();

    try {
      await page.goto(url, { timeout: 30000 });
      const data = await page.content();
      await browser.close();
      return data;
    } catch (error) {
      console.error(`Fehler mit Proxy ${index}:`, error.message);
      rotator.markFailed(index);
      await browser.close();
      
      if (attempt === maxRetries - 1) {
        throw new Error(`Konnte ${url} nach ${maxRetries} Versuchen nicht laden`);
      }
    }
  }
}

Diese Klasse verfolgt nicht funktionierende Proxys und schließt sie von der Rotation aus. Bei einem Fehler wird automatisch auf den nächsten Proxy in der Liste umgeschaltet.

Fehlerbehandlung und Funktionsprüfung

Bei der Arbeit mit Proxys treten spezifische Fehler auf: Verbindungszeitüberschreitungen, Autorisierungsfehler, IP-Blockierungen durch die Zielwebsite. Eine korrekte Fehlerbehandlung ist entscheidend für die Stabilität des Scrapers.

Typische Fehler und deren Behandlung

async function safePageLoad(page, url, options = {}) {
  const defaultOptions = {
    timeout: 30000,
    waitUntil: 'networkidle0',
    maxRetries: 3,
    retryDelay: 2000
  };

  const config = { ...defaultOptions, ...options };

  for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
    try {
      await page.goto(url, {
        timeout: config.timeout,
        waitUntil: config.waitUntil
      });
      
      return { success: true, attempt };
    } catch (error) {
      console.error(`Versuch ${attempt} fehlgeschlagen:`, error.message);

      // Analyse des Fehlertyps
      if (error.message.includes('ERR_PROXY_CONNECTION_FAILED')) {
        throw new Error('Proxy nicht verfügbar');
      }
      
      if (error.message.includes('ERR_TUNNEL_CONNECTION_FAILED')) {
        throw new Error('Proxy-Tunnelfehler');
      }

      if (error.message.includes('407')) {
        throw new Error('Proxy-Autorisierungsfehler (407)');
      }

      if (error.message.includes('Navigation timeout')) {
        console.log(`Ladezeitüberschreitung, Wiederholung in ${config.retryDelay}ms`);
        await new Promise(resolve => setTimeout(resolve, config.retryDelay));
        continue;
      }

      // Wenn dies der letzte Versuch ist - Fehler weitergeben
      if (attempt === config.maxRetries) {
        throw error;
      }
    }
  }
}

Überprüfung der Funktionsfähigkeit von Proxys

async function testProxy(proxyConfig) {
  const browser = await chromium.launch({ proxy: proxyConfig });
  const page = await browser.newPage();

  const result = {
    working: false,
    ip: null,
    responseTime: null,
    error: null
  };

  const startTime = Date.now();

  try {
    await page.goto('https://api.ipify.org?format=json', { timeout: 10000 });
    const content = await page.textContent('body');
    const data = JSON.parse(content);
    
    result.working = true;
    result.ip = data.ip;
    result.responseTime = Date.now() - startTime;
  } catch (error) {
    result.error = error.message;
  } finally {
    await browser.close();
  }

  return result;
}

// Testen der Proxy-Liste
async function validateProxyList(proxyList) {
  console.log('Überprüfung der Proxys...');
  
  const results = await Promise.all(
    proxyList.map(async (proxy, index) => {
      const result = await testProxy(proxy);
      console.log(`Proxy ${index + 1}:`, result.working ? `✓ ${result.ip} (${result.responseTime}ms)` : `✗ ${result.error}`);
      return { proxy, ...result };
    })
  );

  const workingProxies = results.filter(r => r.working);
  console.log(`\nFunktionierende Proxys: ${workingProxies.length}/${proxyList.length}`);
  
  return workingProxies.map(r => r.proxy);
}

Diese Funktion überprüft jeden Proxy vor der Verwendung, misst die Antwortzeit und gibt nur funktionierende Proxys zurück. Es wird empfohlen, die Validierung beim Start der Anwendung durchzuführen.

Überwachung und Protokollierung

class ProxyMonitor {
  constructor() {
    this.stats = {
      totalRequests: 0,
      successfulRequests: 0,
      failedRequests: 0,
      proxyErrors: 0,
      averageResponseTime: 0,
      requestsByProxy: new Map()
    };
  }

  recordRequest(proxyIndex, success, responseTime, error = null) {
    this.stats.totalRequests++;
    
    if (success) {
      this.stats.successfulRequests++;
      this.stats.averageResponseTime = 
        (this.stats.averageResponseTime * (this.stats.successfulRequests - 1) + responseTime) / 
        this.stats.successfulRequests;
    } else {
      this.stats.failedRequests++;
      if (error && error.includes('proxy')) {
        this.stats.proxyErrors++;
      }
    }

    // Statistik für jeden Proxy
    if (!this.stats.requestsByProxy.has(proxyIndex)) {
      this.stats.requestsByProxy.set(proxyIndex, { success: 0, failed: 0 });
    }
    
    const proxyStats = this.stats.requestsByProxy.get(proxyIndex);
    success ? proxyStats.success++ : proxyStats.failed++;
  }

  getReport() {
    const successRate = (this.stats.successfulRequests / this.stats.totalRequests * 100).toFixed(2);
    
    return {
      ...this.stats,
      successRate: `${successRate}%`,
      averageResponseTime: `${this.stats.averageResponseTime.toFixed(0)}ms`
    };
  }
}

// Verwendung
const monitor = new ProxyMonitor();

async function monitoredScrape(url, proxyIndex) {
  const startTime = Date.now();
  try {
    // ... Scraping-Code ...
    const responseTime = Date.now() - startTime;
    monitor.recordRequest(proxyIndex, true, responseTime);
  } catch (error) {
    monitor.recordRequest(proxyIndex, false, 0, error.message);
    throw error;
  }
}

Fortgeschrittene Szenarien: Geolokalisierung und Fingerprinting

Moderne Anti-Bot-Systeme überprüfen nicht nur die IP-Adresse, sondern auch die Übereinstimmung mit Geolokalisierung, Zeitzone, Sprache des Browsers und anderen Parametern. Bei der Verwendung von Proxys aus einem anderen Land ist es wichtig, all diese Parameter korrekt einzustellen.

Einrichtung von Geolokalisierung und Sprache für Proxys

const { chromium } = require('playwright');

async function createContextWithGeo(proxy, geoData) {
  const browser = await chromium.launch({ proxy });
  
  const context = await browser.newContext({
    locale: geoData.locale,           // 'en-US', 'de-DE', 'fr-FR'
    timezoneId: geoData.timezone,     // 'America/New_York', 'Europe/Berlin'
    geolocation: {
      latitude: geoData.latitude,
      longitude: geoData.longitude
    },
    permissions: ['geolocation']
  });

  return { browser, context };
}

// Beispiel: Proxy aus Deutschland
const germanyProxy = {
  server: 'http://de-proxy.example.com:8080',
  username: 'user',
  password: 'pass'
};

const germanyGeo = {
  locale: 'de-DE',
  timezone: 'Europe/Berlin',
  latitude: 52.520008,
  longitude: 13.404954
};

const { browser, context } = await createContextWithGeo(germanyProxy, germanyGeo);
const page = await context.newPage();

await page.goto('https://www.google.com');
// Google zeigt die deutsche Version mit Ergebnissen für Berlin an

Dieser Code konfiguriert den Browser so, dass er wie ein echter Benutzer aus Deutschland aussieht: deutsche Benutzeroberfläche, Berliner Zeitzone und Koordinaten des Zentrums von Berlin.

Vollständige Fingerprint-Konfiguration

async function createStealthContext(proxy, profile) {
  const context = await chromium.launch({ proxy }).then(b => 
    b.newContext({
      locale: profile.locale,
      timezoneId: profile.timezone,
      userAgent: profile.userAgent,
      viewport: profile.viewport,
      deviceScaleFactor: profile.deviceScaleFactor,
      isMobile: profile.isMobile,
      hasTouch: profile.hasTouch,
      colorScheme: profile.colorScheme,
      geolocation: profile.geolocation,
      permissions: ['geolocation']
    })
  );

  return context;
}

// Profil für Windows 10 + Chrome aus den USA
const desktopUSProfile = {
  locale: 'en-US',
  timezone: 'America/New_York',
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
  viewport: { width: 1920, height: 1080 },
  deviceScaleFactor: 1,
  isMobile: false,
  hasTouch: false,
  colorScheme: 'light',
  geolocation: { latitude: 40.7128, longitude: -74.0060 }
};

// Profil für iPhone aus Großbritannien
const mobileUKProfile = {
  locale: 'en-GB',
  timezone: 'Europe/London',
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1',
  viewport: { width: 390, height: 844 },
  deviceScaleFactor: 3,
  isMobile: true,
  hasTouch: true,
  colorScheme: 'light',
  geolocation: { latitude: 51.5074, longitude: -0.1278 }
};

Eine umfassende Fingerprint-Konfiguration verringert die Wahrscheinlichkeit der Entdeckung von Automatisierung. Es ist wichtig, dass alle Parameter zueinander passen: beispielsweise sollte ein mobiler User-Agent mit einer mobilen Bildschirmauflösung kombiniert werden.

Umgehung von WebRTC-Leaks

// Puppeteer: Blockierung von WebRTC
const browser = await puppeteer.launch({
  args: [
    '--proxy-server=http://proxy.example.com:8080',
    '--disable-webrtc',
    '--disable-webrtc-hw-encoding',
    '--disable-webrtc-hw-decoding'
  ]
});

// Playwright: Überschreibung der WebRTC-API
const context = await browser.newContext({ proxy: proxyConfig });

await context.addInitScript(() => {
  // Blockieren von RTCPeerConnection
  window.RTCPeerConnection = undefined;
  window.RTCDataChannel = undefined;
  window.RTCSessionDescription = undefined;
  
  // Überschreiben von getUserMedia
  navigator.mediaDevices.getUserMedia = undefined;
  navigator.getUserMedia = undefined;
});

WebRTC kann Ihre echte IP-Adresse selbst bei Verwendung eines Proxys offenbaren. Dieser Code deaktiviert die WebRTC-API vollständig im Browser.

Vergleich von Puppeteer und Playwright für die Arbeit mit Proxys

Empfehlungen zur Auswahl

Wählen Sie Puppeteer, wenn:

• Sie nur mit Chrome/Chromium arbeiten
• Sie jeweils nur einen Proxy verwenden
• Maximale Kompatibilität mit bestehenden Tools erforderlich ist
• Sie bereits eine große Codebasis in Puppeteer haben

Wählen Sie Playwright, wenn:

• Sie mit Firefox oder Safari (WebKit) arbeiten müssen
• Gleichzeitige Nutzung mehrerer Proxys erforderlich ist
• Leistung bei der Skalierung wichtig ist
• Sie in TypeScript schreiben
• Sie ein neues Projekt von Grund auf neu starten

Leistung bei der Proxy-Rotation

Test: Scraping von 100 Seiten mit Rotation von 10 Proxys auf einem MacBook Pro M1:

Playwright mit einem Kontext-Pool ist fast doppelt so schnell, da die Kosten für den Browserstart entfallen. Dies ist entscheidend beim Scraping von Tausenden von Seiten.

Fazit

Die Integration von Proxys in Puppeteer und Playwright ist eine gängige Praxis für Web-Scraping, Tests und Automatisierung. Puppeteer bietet Einfachheit und ein breites Ökosystem, während Playwright eine moderne API und bessere Leistung bei der Arbeit mit mehreren Proxys über Browserkontexte bietet.

Wichtige Punkte, die wir behandelt haben:

• Grundlegende Einrichtung von HTTP-, HTTPS- und SOCKS5-Proxys in beiden Frameworks
• Authentifizierung mit Benutzername und Passwort
• Proxy-Rotation für großflächiges Scraping
• Fehlerbehandlung und Validierung von Proxys vor der Verwendung
• Einrichtung von Geolokalisierung und Fingerprinting zur Umgehung von Anti-Bot-Systemen
• Vergleich der Leistung verschiedener Ansätze

Für Produktionslösungen empfehlen wir die Kombination von hochwertigen Proxys mit einer korrekten Fingerprint-Einstellung, Fehlerbehandlung und Überwachung. Dies gewährleistet einen stabilen Betrieb des Scrapers, selbst auf geschützten Websites.

Wenn Sie planen, kommerzielle Websites, Marktplätze oder Werbeplattformen zu scrapen, empfehlen wir die Verwendung von residential Proxys — sie bieten maximale Anonymität und minimales Risiko von Blockierungen durch echte IP-Adressen von Haushaltsnutzern.