Puppeteer Proxy Setup: Vlaggen, Auth, Rotatie en Realiteit

De startvlag is eenvoudig; de 407 die volgt is waar de meeste Puppeteer proxy setups vastlopen. Hier is het volledige patroon — page.authenticate, contextrotatie, proxy-chain — en de waarheid over per-pagina proxies en headless detectie.

Puppeteer proxy setup begint met één startvlag en, voor de meeste mensen, stopt één stap later bij een muur: de proxy antwoordt 407 Proxy Authentication Required, omdat --proxy-server geen manier heeft om inloggegevens mee te geven. De oplossing is ingebouwd — page.authenticate() — maar eromheen ligt een mijnenveld van halfwerkende adviezen: npm-pakketten die stilletjes je verkeer omleiden via Node.js, SOCKS-schema's die Chromium niet zal authenticeren, en een localhost bypass die werkende proxies dood laat lijken. Deze gids beschrijft de setup die standhoudt in productie: vlaggen, auth, rotatie met browsercontexten, proxy-chain voor de lastige gevallen, en een eerlijk deel over headless detectie.

Puppeteer proxy setup: het basispatroon

De proxy is een Chromium startargument, dus het geldt voor de hele browser. Inloggegevens gaan via page.authenticate(), dat de 407-uitdaging van de proxy beantwoordt via het DevTools-protocol — roep het aan vóór enige navigatie:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gate.quantumproxies.io:PORT'],
  });
  const page = await browser.newPage();
  await page.authenticate({ username: 'USER', password: 'PASS' });

  await page.goto('https://httpbin.org/ip', { waitUntil: 'domcontentloaded' });
  console.log(await page.evaluate(() => document.body.innerText)); // exit IP
  await browser.close();
})();

Vier details besparen uren debuggen:

• Bouw de vlag met een template literal of concatenatie, niet met gewone aanhalingstekens. Een klassiek Stack Overflow probleem: "--proxy-server =..." in dubbele aanhalingstekens met een interpolatieplaatsvervanger vervangt nooit de variabele — en de verdwaalde spatie breekt ook de parsing.
• Voeg het schema toe. --proxy-server=socks5://host:port voor SOCKS, anders neemt Chromium aan dat het HTTP is.
• Embed user:pass@ niet in de vlag. Chromium negeert het; alleen page.authenticate() (of IP-whitelisting) authenticeert.
• Localhost omzeilt de proxy. Chromium slaat proxies over voor loopback-URL's — een puzzel gedocumenteerd in Puppeteer issue #3711. Voeg --proxy-bypass-list=<-loopback> toe als je echt lokaal verkeer moet proxieren; anders test je gewoon tegen een externe URL.

Proxies roteren met browsercontexten

Chrome opnieuw opstarten per IP kost seconden en honderden MB elke keer. Browsercontexten lossen dat op: sinds Puppeteer v22 is de API browser.createBrowserContext() (vervangt de oude incognito-variant), het accepteert een proxyServer optie, en een context wordt in milliseconden gecreëerd met zijn eigen cookies en opslag:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const jobs = ['https://example.com/a', 'https://example.com/b'];

  for (const url of jobs) {
    const context = await browser.createBrowserContext({
      proxyServer: 'http://gate.quantumproxies.io:PORT',
    });
    const page = await context.newPage();
    await page.authenticate({ username: 'USER', password: 'PASS' });
    try {
      await page.goto(url, { timeout: 30000 });
      // ...extract...
    } finally {
      await context.close();
    }
  }
  await browser.close();
})();

Tegen een roterende gateway verlaat elke context van nature een ander adres in de pool — met roterende residentiële proxies zijn dat 90M+ IP's in 200+ landen achter één hostname, en een sticky-session gebruikersnaamparameter fixeert een exit wanneer een multi-pagina flow continuïteit nodig heeft. Dit is dezelfde context-per-taak architectuur die we aanbevelen voor Playwright; Puppeteer spelt alleen de auth-stap expliciet uit.

Twee gewoonten houden rotatie eerlijk. Log het exit-IP per context tijdens ontwikkeling — raak een IP-echo eindpunt aan bij contextstart en sla het op met je gescrapete rijen, zodat wanneer een doelwit je zacht begint te blokkeren je kunt zien of één exit of één vingerafdruk de boosdoener is. En begrens je gelijktijdigheid: elke context is goedkoop, maar elke geopende pagina houdt nog steeds rendergeheugen vast, dus een semafoor rond contextcreatie verslaat een onbeperkte lus de eerste keer dat een takenlijst groeit tot duizenden URL's.

proxy-chain: de lokale brug voor lastige auth

Twee gevallen breken het vlag-plus-authenticate patroon: geauthenticeerde SOCKS5 (Chromium heeft helemaal geen SOCKS inlogmechanisme) en tools die alleen een kale proxy-URL accepteren zonder auth-stap. Het proxy-chain npm-pakket lost beide op door een lokale, inlogvrije proxy te starten die doorstuurt naar je geauthenticeerde upstream:

const puppeteer = require('puppeteer');
const proxyChain = require('proxy-chain');

(async () => {
  const upstream = 'http://USER:PASS@gate.quantumproxies.io:PORT';
  const localUrl = await proxyChain.anonymizeProxy(upstream);
  // localUrl is something like http://127.0.0.1:54321 — no credentials needed

  const browser = await puppeteer.launch({
    args: ['--proxy-server=' + localUrl],
  });
  const page = await browser.newPage();
  await page.goto('https://httpbin.org/ip');

  await browser.close();
  await proxyChain.closeAnonymizedProxy(localUrl, true);
})();

Cruciaal is dat de verzoeken van de pagina nog steeds van Chrome zelf vertrekken — proxy-chain stuurt alleen bytes door, dus je TLS-vingerafdruk blijft die van een echte browser. Dat onderscheid is het volgende deel.

Per-pagina proxies: het eerlijke antwoord

Puppeteer heeft geen native per-pagina proxy, en de populaire workarounds — puppeteer-page-proxy, puppeteer-proxy — onderscheppen elk verzoek en geven het opnieuw uit vanuit Node.js met een HTTP-bibliotheek, en voeren dan de respons terug naar de browser. Drie gevolgen: het doelwit ziet nu een Node TLS-handshake in plaats van die van Chrome, wat JA3/JA4 vingerafdrukken onmiddellijk markeert op beschermde sites; elk verzoek betaalt een roundtrip door Node; en beide pakketten worden effectief niet onderhouden, met installatie die kapot is uit de doos volgens hun eigen issue trackers. Als je verschillende IP's voor verschillende pagina's nodig hebt, gebruik dan één context per proxy zoals hierboven — hetzelfde effect, echt Chrome-verkeer, ondersteunde API.

Headless detectie realiteit

Een proxy repareert de netwerklag; het kan headless Chrome niet onzichtbaar maken. De oude headless modus kondigde zichzelf aan met een HeadlessChrome User-Agent token; de nieuwe headless (Puppeteer's standaard sinds v22) deelt de architectuur van de echte browser en sluit veel van die kloof, maar detectors onderzoeken nog steeds navigator.webdriver, CDP bijwerkingen en weergave-eigenaardigheden — en stealth plugins patchen de controles van gisteren, niet die van morgen. Orden je oplossingen op basis van rendement op inspanning: een schone residentiële IP eerst, omdat reputatie het goedkoopste filter is voor sites om te draaien en het enige dat je code niet kan vervalsen; verstandige headers en pacing als tweede (onze gids over het vermijden van CAPTCHA's behandelt de triggersignalen); en wanneer een gehard doelwit nog steeds wint, routeer dat domein dan via een Scraper API die rendering, vingerafdrukken en retries afhandelt en schone HTML, markdown of JSON retourneert — één HTTP-aanroep in plaats van een vloot van gepatchte browsers.

Veelgestelde vragen

Hoe authenticeer ik een proxy in Puppeteer?

Stel het adres in met args: ['--proxy-server=http://host:port'] bij de start, roep dan await page.authenticate({ username, password }) aan op elke pagina voordat je navigeert. Inloggegevens ingebed in de vlag-URL worden genegeerd door Chromium. Voor SOCKS5 met auth, brug via proxy-chain in plaats daarvan, omdat Chromium geen SOCKS inloggegevens kan verzenden.

Kan Puppeteer een andere proxy per pagina gebruiken?

Niet native — de startvlag is browserbreed. Het ondersteunde equivalent is één browsercontext per proxy via browser.createBrowserContext({ proxyServer }), met pagina's binnen elke context. Pakketten die echte per-pagina proxies beloven, leiden verzoeken om via Node.js, waardoor je TLS-vingerafdruk verandert en je wordt gemarkeerd door serieuze anti-bot systemen.

Ondersteunt Puppeteer SOCKS5 proxies?

Ja voor niet-geauthenticeerde eindpunten: geef --proxy-server=socks5://host:port door. Geauthenticeerde SOCKS5 mislukt omdat Chromium geen SOCKS inlogmechanisme heeft en page.authenticate() alleen HTTP 407-uitdagingen beantwoordt. Workarounds: gebruik de HTTP-poort van de gateway met authenticatie, whitelist je IP, of draai proxy-chain als een lokale brug.

Hoe roteer ik proxies in Puppeteer?

Maak een nieuwe browsercontext per taak met createBrowserContext({ proxyServer }) en wijs deze naar een roterende gateway — elke context verlaat dan automatisch een nieuw IP, zonder een proxy-lijst te beheren. Het hele browser opnieuw opstarten per IP werkt ook maar kost seconden en honderden MB RAM per rotatie.

Waarom werkt mijn Puppeteer proxy niet voor localhost?

Chromium omzeilt proxies voor loopback-adressen van nature, dus verzoeken naar localhost of 127.0.0.1 gaan direct — gedrag dat genoeg mensen verraste om een genummerde Puppeteer issue te worden. Voeg --proxy-bypass-list=<-loopback> toe om proxying af te dwingen, of verifieer je proxy simpelweg tegen een extern IP-echo eindpunt.

Het duurzame patroon is klein: vlag voor het adres, page.authenticate() voor de inloggegevens, contexten voor rotatie, proxy-chain voor de hoekgevallen — en scepticisme voor elk pakket dat je verzoeken uit de browser verplaatst. Geef die stack schone residentiële exits en Puppeteer blijft saai, wat het grootste compliment is dat infrastructuur kan krijgen.

Draai Puppeteer op residentiële proxies