puppeteer-cluster-Captcha: Mit einem Token pro Task lösen

Um ein puppeteer-cluster-Captcha zu lösen, rufen Sie den Solver innerhalb der Task-Funktion auf und halten Sie den Token in einer lokalen Konstante. Ein reCAPTCHA-Token funktioniert nur einmal, daher kann ein zwischen Tasks geteilter Token nur ein Formular passieren. Dieser Leitfaden baut das Skript mit dem Node.js-Paket capskip, das unter einer Pauschallizenz mit der CapSkip-App auf Ihrem eigenen Windows-PC spricht, und legt dann drei Limits fest: maxConcurrency, das Cluster-Timeout und retryLimit. Die Version für eine einzelne Seite steht auf der Puppeteer-Captcha-Solver-Seite.
Was Sie brauchen
- CapSkip läuft auf einem Windows-PC und wird über Host und Port erreicht (standardmäßig 127.0.0.1 und 8080). Der Server-Modus lässt es auf Ihrem Netzwerk oder Ihrer öffentlichen IP lauschen, sodass ein Cluster auf einem anderen PC denselben Solver nutzen kann. Die Verbindungseinstellungen schalten zwischen beiden um.
- Node.js 22.12 oder neuer für Puppeteer 25.17.0 (laut dessen Feld engines) oder Node.js 18 oder neuer für Puppeteer 24.43.1. Ich habe Node 24.22.0 und 25.2.1 mit der ersten und Node 20.11.1 und 24.22.0 mit der zweiten ausgeführt, nicht Node 18 oder 22.
- puppeteer-cluster 0.25.0 (kein Feld engines, Peer-Bereich Puppeteer 24.0.0 oder neuer) und capskip 1.7.0 (Node 18 oder neuer), die Versionen, die ich ausgeführt habe.
- Eine Seite, die Sie automatisieren dürfen und die eine reCAPTCHA-v2-Checkbox zeigt.
Prüfen Sie, wie aktuell die Bibliothek ist. Als ich im November 2026 nachsah, war 0.25.0 (13. November 2025) die neueste Version, master hatte keinen neueren Commit, und 112 Issues und 16 Pull Requests waren offen. Sie ist nicht archiviert, und die README von puppeteer-cluster zeigt, ob dieses Tempo zu Ihnen passt.
Wie das puppeteer-cluster-Captcha-Skript getestet wurde: weder gegen die echte CapSkip-App noch gegen eine echte reCAPTCHA-Seite. Jeder Lauf verwendete einen von mir geschriebenen Mock von in.php und res.php sowie eine Ersatz-Formular-Website mit einem g-recaptcha-div, einem Attribut data-sitekey und einem versteckten textarea namens g-recaptcha-response. Es ist nicht das Widget von Google. Die Regeln sind meine: eine Verwendung pro Token, ein Token muss zum sitekey seiner Seite passen, und das Formular braucht sein CSRF-Cookie. Der Mock lehnt außerdem einen sitekey ab, der die Formregel verletzt, die ich im Quellcode der CapSkip-App gelesen habe. Die meisten Läufe nutzten Chrome for Testing 156.0.8078.47 über PUPPETEER_EXECUTABLE_PATH, und der Installationsblock funktionierte wie geschrieben auch mit dem Chrome, das npm herunterlädt (157.0.8103.50 für Puppeteer 25.17.0, 148.0.7778.97 für 24.43.1). npm 11 warnt, dass [email protected] ein Installationsskript hat, das noch nicht von allowScripts abgedeckt ist, aber der Download fand trotzdem statt. Bei abgeschalteten Installationsskripten stoppt das Skript mit Could not find Chrome.
Das Skript bauen
Schritt 1: Das Projekt und die Einstellungen anlegen
Legen Sie zuerst package.json an: Mit npm 11.19.1 unter Windows landeten die Pakete in einem Ordner ohne diese Datei in einem übergeordneten Ordner.
# PowerShell. Make the folder and its package.json first: with no # package.json here, npm installs into the nearest parent folder that has one. mkdir captcha-cluster cd captcha-cluster npm init -y npm install puppeteer puppeteer-cluster capskip
Verwenden Sie unter Node.js 18 bis 22.11 npm install puppeteer@24 puppeteer-cluster capskip stattdessen. Die obige Zeile installierte unter Node 20.11.1 Puppeteer 25.17.0 mit EBADENGINE-Warnungen, und das Skript starb dann mit ERR_REQUIRE_ESM.
Beginnen Sie als Nächstes eine Datei namens cluster-solve.js. Dieser Block und die Blöcke in Schritt 2 bis 4 kommen der Reihe nach hinein, und nichts läuft, bevor der letzte drin ist. Das SDK liest keine der CAPSKIP-Variablen von selbst, daher liest das Skript Host und Port selbst daraus.
// cluster-solve.js: this block and the ones in Steps 2 to 4 go into one file.
const { Cluster } = require("puppeteer-cluster");
const { CapSkip, ApiException, ValidationException } = require("capskip");
const SOLVE_TIMEOUT = 90; // seconds the SDK waits for one token
const TASK_TIMEOUT = 150000; // milliseconds the cluster allows one whole task
const MAX_PAGES = 3; // tasks running at once, so also solves in flight
const RETRIES = 1; // extra attempts after a failed task
// Local mode is 127.0.0.1. In Server mode, set CAPSKIP_HOST to your CapSkip PC.
const solver = new CapSkip({
host: process.env.CAPSKIP_HOST || "127.0.0.1",
port: Number(process.env.CAPSKIP_PORT || 8080),
recaptchaTimeout: SOLVE_TIMEOUT,
});
// Comma separated addresses of the pages that show the widget.
const FORM_URLS = (process.env.FORM_URLS || "https://example.com/form/1").split(",");
const outcomes = []; // one entry per task that finished without throwingSchritt 2: Innerhalb des Tasks lösen
Jeder Task lädt seine Seite, liest den sitekey, fragt CapSkip nach einem Token für die Adresse dieser Seite, schreibt ihn in das versteckte textarea und drückt Absenden. Auf einer echten Seite erscheint dieses textarea, sobald das Skript von Google das Widget gerendert hat, was die Lösezeit normalerweise abdeckt; ich habe nur ein statisches getestet. Deklariert Ihre Website ein data-callback, rufen Sie es nach dem Schreiben des Tokens auf; mein Ersatz hat keines, daher habe ich das nicht getestet. Die Prüfung auf Status 200 passt nur zum Ersatz; echte Websites zeigen das Formular oft mit einem Fehler bei 200 erneut. Die Anleitung zu reCAPTCHA v2 in Node.js behandelt den Ablauf für eine einzelne Seite.
async function submitWithToken(page, url, token) {
// Write the token into the widget's hidden textarea, then press submit.
await page.$eval("#g-recaptcha-response", (el, value) => { el.value = value; }, token);
const [response] = await Promise.all([
page.waitForNavigation({ waitUntil: "domcontentloaded" }),
page.click("button[type=submit]"),
]);
if (response.status() !== 200) {
throw new Error(`site answered ${response.status()} for ${url}`);
}
outcomes.push({ url, ok: true });
}
async function solveForm({ page, data }) {
await page.goto(data.url, { waitUntil: "domcontentloaded" });
const sitekey = await page.$eval(".g-recaptcha", (el) => el.dataset.sitekey);
// The token is a local constant, so no other task can read or reuse it.
const { code: token } = await solver.recaptcha(sitekey, page.url());
await submitWithToken(page, data.url, token);
}Schritt 3: Nur wiederholen, was ein Retry beheben kann
retryLimit wiederholt jeden Fehler, den ein Task auslöst, daher prüft dieser Wrapper zuerst den Fehlertyp. Eine ApiException mit ERROR_CAPTCHA_UNSOLVABLE bedeutet, dass CapSkip diesen Task nicht lösen konnte, und ein neuer kann klappen. Jede andere ApiException und jede ValidationException stammt aus Ihrer Anfrage oder Ihren Limits, daher protokolliert der Wrapper sie und beendet den Task. Mit Standardeinstellungen lehnt CapSkip einen fehlenden oder fehlerhaften sitekey sofort ab (ERROR_GOOGLEKEY in der API-Dokumentation), was im Wrapper endet; die Einstellung, die Tasks mit ungültigen Daten auflistet, ist standardmäßig aus. Der Wrapper wiederholt keine Ablehnung wegen fehlenden Slots, weil das Cluster sofort in dieselbe volle Queue zurückwiederholen würde: Senken Sie maxConcurrency stattdessen. Im gelesenen App-Quellcode wird ein wohlgeformter Key, der für die Seite falsch ist, als unlösbar beantwortet, daher wird er wiederholt, bis retryLimit aufgebraucht ist.
// Decide from the error type whether a second attempt could end differently.
function retryWouldHelp(err) {
if (err instanceof ValidationException) return false; // the arguments are wrong
if (err instanceof ApiException) return err.message.includes("ERROR_CAPTCHA_UNSOLVABLE");
return true; // timeouts, network trouble, a site that said no
}
async function solveFormGuarded(job) {
try {
await solveForm(job);
} catch (err) {
if (retryWouldHelp(err)) throw err; // the cluster decides whether to retry
outcomes.push({ url: job.data.url, ok: false, error: err.message });
}
}Schritt 4: Das Cluster starten und die Seiten einreihen
Chrome startet standardmäßig headless, wie ich in der Befehlszeile des gestarteten Browsers gesehen habe.
(async () => {
const cluster = await Cluster.launch({
concurrency: Cluster.CONCURRENCY_CONTEXT, // a private cookie jar per task
maxConcurrency: MAX_PAGES,
timeout: TASK_TIMEOUT,
retryLimit: RETRIES,
});
// Without this listener a failed task gives no reason at all.
cluster.on("taskerror", (err, data, willRetry) => {
console.error(`${data.url}: ${err.message}${willRetry ? " (will retry)" : ""}`);
});
await cluster.task(solveFormGuarded);
for (const url of FORM_URLS) cluster.queue({ url });
await cluster.idle();
await cluster.close();
const accepted = outcomes.filter((o) => o.ok).length;
console.log(`${accepted} of ${FORM_URLS.length} forms accepted`);
for (const o of outcomes.filter((o) => !o.ok)) console.log(`gave up: ${o.url} ${o.error}`);
process.exitCode = accepted === FORM_URLS.length ? 0 : 1;
})();# PowerShell, in the project folder. Name the pages, then run the script. $env:FORM_URLS = "https://example.com/form/1,https://example.com/form/2" node cluster-solve.js
Gegen den Mock ergaben acht Formulare, drei Seiten und eine Mock-Lösung von 2 Sekunden 8 von 8 akzeptierte Formulare und höchstens 3 gleichzeitige Lösungen. Eine Lösung dauerte vom Absenden bis zum Token 3,8 Sekunden, nicht 2, weil das SDK bei 0, 0,25, 0,75, 1,75 und 3,75 Sekunden abfragt. Die anderen Laufzeit-Setups stimmten überein, ohne dass eine Warnung protokolliert wurde.
Warum ein puppeteer-cluster-Captcha-Token im Task bleibt
Die verlockende Abkürzung ist eine Variable über der Task-Funktion, eine Form, die das Skript weglässt.
// Do not add this. One variable shared by every task is the bug.
let sharedToken = null;
async function solveFormShared({ page, data }) {
await page.goto(data.url, { waitUntil: "domcontentloaded" });
const sitekey = await page.$eval(".g-recaptcha", (el) => el.dataset.sitekey);
if (!sharedToken) {
sharedToken = (await solver.recaptcha(sitekey, page.url())).code;
}
await submitWithToken(page, data.url, sharedToken);
}Im Mock ergaben sechs Formulare 3 Lösungen, 3 akzeptierte Formulare und 6 Ablehnungen, Retries eingeschlossen. Die ersten drei Tasks sehen eine leere Variable und bestehen. Jeder spätere Task verwendet den zuletzt gespeicherten Token wieder, der zu einem anderen sitekey gehört oder bereits verbraucht ist. Das Skript in der geschriebenen Form machte 8 Lösungen für 8 Formulare ohne Ablehnung.
Die andere Falle ist das Cookie-Jar. Der Standardmodus, CONCURRENCY_CONTEXT, gibt jedem Task einen privaten Browser-Kontext, und CONCURRENCY_PAGE teilt einen. Mein Ersatz setzt bei jedem Seitenaufruf ein frisches CSRF-Cookie, daher scheitern früher geladene Tasks. Acht Formulare brauchten in 10 Läufen 12 bis 14 Lösungen, 5 bis 8 CSRF-Ablehnungen und 6 oder 7 akzeptierte Formulare. Eine Website mit einem stabilen Cookie würde nicht brechen.
Drei Limits, die zusammenpassen müssen
In einem puppeteer-cluster-Captcha-Skript gilt für die puppeteer-cluster-Option maxConcurrency Folgendes: Sie begrenzt die gleichzeitig laufenden Lösungen, denn jeder Task macht eine, und 0 bedeutet kein Limit. CapSkip hat sein eigenes Limit: die Einstellung "Max. Threads" in der reCAPTCHA-Zeile der Settings, standardmäßig 10. Zusätzliche Tasks warten in dessen Queue bis zu "Wait Timeout" (standardmäßig 250 Sekunden), und das SDK-Timeout schließt dieses Warten ein. Im Mock mit zwei Lösungs-Slots und vier Seiten brauchte eine Lösung von 4 Sekunden 7,8 Sekunden vom Absenden bis zum Token ohne Wartezeit und 12,8 mit Warten auf einen Slot, weil das SDK einen Token bei seiner ersten Prüfung nach Ende der Lösung abholt und bei etwa 3,8, 7,8 und 12,8 Sekunden prüft. Die Queue ist außerdem kurz. Das Changelog sagt, dass seit CapSkip 2.4.0 ein reCAPTCHA-Task, der bei voller Queue eintrifft, mit einem No-Slot-Fehler abgelehnt wird, und im gelesenen App-Quellcode ist die Queue so tief wie "Max. Threads". Mein Mock wendet diese Regel an: Mit zwei Lösungs-Slots, einer Queue von zwei und acht gleichzeitigen Seiten wurden 4 Formulare akzeptiert, und bei 4 endete es mit ERROR_NO_SLOT_AVAILABLE, während vier Seiten für 8 von 8 genügten. Halten Sie maxConcurrency höchstens auf dem Wert von "Max. Threads", und denken Sie daran, dass zwei Cluster an einem CapSkip ihn teilen. Jede laufende Lösung nutzt außerdem eine IP-Adresse, und die Einrichtungsanleitung sagt, Sie sollten CapSkip mindestens so viele Proxys geben wie "Max. Threads".
Das Timeout des puppeteer-cluster muss das Warten des SDK plus die Seitenarbeit übersteigen. Der Cluster-Standard sind 30 Sekunden, und das SDK wartet bei reCAPTCHA 300, es sei denn, Sie setzen recaptchaTimeout. Ohne die Option timeout und bei einer Mock-Lösung von 40 Sekunden, Timeout hit: 30000 erschien etwa 31 Sekunden nach dem Start des Skripts, aber der Prozess endete erst bei etwa 44, weil der aufgegebene Task weiter abfragte. Ein SDK-Limit von 3 Sekunden löste bei 3,8 Sekunden aus, weil das SDK seine Frist nur zwischen den Abfragen prüft.
Ein Timeout stoppt die Lösung nicht. Im Mock ergab bei einer Lösung von 12 Sekunden, vier Formularen, zwei Seiten und einem Retry ein Cluster-Timeout von 5 Sekunden 8 Lösungen für 4 Formulare, bis zu 6 gleichzeitig bei 2 Seiten und 8 Tokens, die an Tasks geliefert wurden, die bereits gescheitert waren. Ein SDK-Warten von 3 bei einem Cluster-Timeout von 9 ergab timeout 3 exceeded und dennoch 8 Lösungen. Ob ein echtes CapSkip eine Lösung verwirft, die niemand abfragt, wurde hier nicht gemessen. Die Einrichtungsanleitung sagt, dass eine Lösung, die ihr "Row Timeout" überdauert (250 Sekunden bei reCAPTCHA), gestoppt wird, und im gelesenen App-Quellcode habe ich keinen Code gefunden, der einen Job abbricht, wenn das Abfragen aufhört (gelesen, nicht ausgeführt).
Fehler, retryLimit und stille Fehlschläge
Die puppeteer-cluster-Option retryLimit zählt zusätzliche Versuche: 1 bedeutet zwei Versuche, 2 bedeutet drei. Eine Seite, die der Mock einmal als unlösbar abgelehnt hat, wurde beim Retry akzeptiert, und mit retryLimit 0 schlug sie fehl, und der Exit-Code war 1.
Ohne Schritt 3 werden Fehler, die kein Retry beheben kann, trotzdem wiederholt. Bei retryLimit 2 brauchte ein fehlerhafter sitekey drei Versuche, ebenso eine nicht unterstützte Option, die das SDK als ValidationException meldet. Mit dem Wrapper brauchte jeder einen. Ein wohlgeformter Key, den der Mock immer als unlösbar meldete, brauchte weiterhin alle drei.
cluster.execute() überspringt die Retry-Regeln, die retryLimit festlegt: Auf der Seite, die einmal unlösbar war, bei retryLimit 2 wurde sie nach einem Versuch abgelehnt, während cluster.queue() wiederholte. Ein fehlschlagender eingereihter Task ist außerdem stumm: Ohne taskerror -Listener und ohne DEBUG-Variable druckte ein fehlgeschlagener Lauf nur die Zusammenfassung. Das Setzen von DEBUG=puppeteer-cluster:log druckte eine Zeile pro Fehler.
| Was Sie sehen | Ursache | Beheben |
|---|---|---|
Timeout hit: 30000 | Das Cluster-Standardlimit beendete den Task, während CapSkip noch löste | Setzen Sie das Cluster-Timeout über das Warten des SDK |
timeout 90 exceeded | Das SDK hat aufgehört, auf einen Token zu warten | Messen Sie die Lösungen auf Ihrem PC und erhöhen Sie dann beide Timeouts |
ERROR_GOOGLEKEY | Der sitekey fehlt oder hat nicht die Form eines reCAPTCHA-Keys | Prüfen Sie den Selektor, der den sitekey liest; wiederholen Sie nicht |
ERROR_NO_SLOT_AVAILABLE | Es erreichten mehr Tasks CapSkip, als dessen Queue fasst | Legen Sie fest maxConcurrency auf höchstens "Max. Threads" |
ERROR_PAGEURL | Die Seitenadresse fehlt oder ist keine http- oder https-Adresse | Übergeben Sie die Adresse der geladenen Seite; wiederholen Sie nicht |
connect ECONNREFUSED 127.0.0.1:12999 | Auf diesem Port lauscht nichts | Starten Sie CapSkip und prüfen Sie Host und Port |
| Die Website lehnt die meisten Einsendungen ab (mein Ersatz antwortet mit 403; Ihre antwortet vielleicht mit 200 und einer Fehlerseite) | Ein geteilter Token oder ein geteiltes Cookie-Jar | Halten Sie den Token lokal; verwenden Sie den Standardmodus |
CapSkip auf einem Server verwenden
Ein puppeteer-cluster-Captcha-Skript braucht nur einen Host und einen Port. Der Local-Modus lauscht auf 127.0.0.1, daher muss das Cluster auf diesem PC laufen. Der Server-Modus lauscht auf Ihrem Netzwerk oder Ihrer öffentlichen IP, und Sie setzen CAPSKIP_HOST auf diesen Windows-PC. Ich habe nur 127.0.0.1 getestet. Der Server-Modus startet damit, dass CapSkip seinen Port von jeder Adresse zulässt, und eine eigene Allow-Regel würde das nicht einschränken, also fügen Sie für die Adressen, die draußen bleiben sollen, eine Block-Regel der Windows-Firewall hinzu.
FAQ
Funktioniert puppeteer-cluster mit dem aktuellen Puppeteer?
Das Skript lief auf Puppeteer 25.17.0 und 24.43.1. Wenn Sie lieber keinen Pool selbst verwalten möchten, behandelt der Crawlee-Leitfaden einen Crawler mit eigener Parallelität und eigenen Retries.
Kann ich zuerst jede Seite lösen und das Cluster danach laufen lassen?
Nicht sicher. Die Dokumentation zur reCAPTCHA-Verifizierung sagt, ein Token lebt zwei Minuten und funktioniert nur einmal, daher kann einer, der erstellt wurde, bevor sein Task eine freie Seite erreicht, veraltet sein. Fordern Sie ihn innerhalb des Tasks an, wie es das Skript tut.
Die Kurzfassung
Ein puppeteer-cluster-Captcha-Skript läuft auf eine Lösung pro Task hinaus, auf einen Token in einer lokalen Konstante und auf Limits, die zusammenpassen: maxConcurrency höchstens so hoch wie die Zahl, die CapSkip gleichzeitig löst, ein Cluster-Timeout, das länger ist als das Warten des SDK, und Retries nur für Fehler, die ein Retry beheben kann. CapSkip ist ein lokaler Captcha-Löser mit Pauschallizenz, daher kostet ein Retry Zeit auf Ihrem eigenen PC und keine Gebühr pro Lösung. Dasselbe Paket löst mehr als reCAPTCHA, und die Node.js-Captcha-Solver-Seite zeigt, welche Typen.
