GeeTest v4 in Node.js: Registrierungen im Stapel mit fetch und Typen

Um GeeTest v4 in Node.js ohne Browser zu lösen, lesen Sie die captcha_id einmal von der Seite, rufen Sie solver.geetestV4() aus dem Paket capskip mit dieser ID und der Seitenadresse auf und senden Sie die fünf zurückgegebenen Felder unter denselben Namen in der Anfrage, die die Seite selbst stellt. Das Skript unten macht das für sechs Registrierungen mit dem eingebauten fetch, mit einer frischen Lösung pro Übermittlung, und endet mit Promise.allSettled. Die Aufgaben löst der CapSkip-GeeTest-v4-Löser auf Ihrem eigenen Windows-PC, ohne Gebühr pro Lösung.
Was Sie brauchen
- Ein Windows-Rechner mit CapSkip 5.0.0 oder neuer, der ersten Version, die laut Changelog GeeTest v4 löst.
- Node.js 18 oder neuer, was das Feld engines von capskip 1.8.0 deklariert. Das ist die erste SDK-Version mit geetestV4(). Meine Läufe umfassten 20.11.1, 24.22.0 und 25.2.1, ich habe also Node.js 18 selbst nie ausgeführt.
- TypeScript, aber nur für die optionale Typprüfung. Zum Zeitpunkt des Schreibens löste npm typescript 7.0.2 auf, das Node.js 16.20 oder neuer deklariert, und @types/node 26.6.6.
- Eine Registrierungs- oder Anmeldeseite mit einem GeeTest-v4-Widget, die Sie automatisieren dürfen.
- Eine Adresse für CapSkip. Local mode hält es auf 127.0.0.1. Server mode nimmt auch Verbindungen aus Ihrem Netzwerk oder von einer öffentlichen IP an, und der Abschnitt Connection Settings der Einrichtungsanleitung beschreibt beide Modi.
Jeder Lauf unten nutzte zwei kleine Server, die ich geschrieben habe, einen, der die CapSkip-API nachahmt, und einen, der eine Registrierungsseite nachahmt, wodurch die Website-Regeln von mir stammen. Die echte CapSkip-App antwortete beim Testen auf diesem PC nicht, daher habe ich ihr nichts gesendet, und keine GeeTest-Website sah eine Anfrage. Wo eine Aussage statt auf einem Lauf auf der CapSkip-Dokumentation, dem SDK-Quellcode oder der GeeTest-Dokumentation beruht, sage ich das. Eine echte Website prüft die fünf Felder auf ihrem eigenen Server mit ihrem privaten Schlüssel über die GeeTest-API zur Server-Validierung.
Schritt 1: den Ordner einrichten
Führen Sie den ersten Block in einem leeren Ordner aus. Er erstellt package.json, installiert capskip und fügt TypeScript für die Typprüfung hinzu. Speichern Sie den Block tsconfig als tsconfig.json. Speichern Sie dann die vier JavaScript-Blöcke der Schritte 2 bis 5 der Reihe nach als eine Datei namens geetest_v4.mjs. Die Endung .mjs erlaubt Top-Level-await. Ändern Sie vor dem ersten Lauf ORIGIN, die beiden Pfade und die E-Mail-Adressen auf Ihre eigene Website. Unverändert fragt das Skript example.com an und stoppt mit "the page answered HTTP 404".
# Run in an empty folder, in PowerShell or any other shell npm init -y npm install capskip npm install --save-dev typescript @types/node
{
"compilerOptions": {
"target": "es2022",
"module": "node16",
"moduleResolution": "node16",
"allowJs": true,
"checkJs": true,
"noEmit": true,
"strict": true,
"skipLibCheck": true,
"types": ["node"]
},
"files": ["geetest_v4.mjs"]
}Mit dieser Datei liest tsc das Skript als typisiertes JavaScript. Das Paket liefert GeetestV4Options und ein SolveResult, dessen fünf GeeTest-Felder optional sind, daher hat Schritt 3 eine Absicherung.
Schritt 2: die captcha_id einmal lesen
Die Seite übergibt die ID als captchaId an initGeetest4, und die Anfrage an gcaptcha4.geetest.com/load trägt sie als captcha_id, nach Angaben von CapSkip in der GeeTest-v4-API-Dokumentation. Sie ist für jeden Besucher gleich, daher behält readCaptchaId ihr Promise in einer Variablen und ruft die Seite einmal pro Lauf ab, egal wie viele Übermittlungen folgen. Es sammelt jeden Treffer in einem Set und weigert sich zu raten: Zwei verschiedene IDs oder keine lassen jede Übermittlung scheitern, bevor eine Lösung angefordert wird. Es cacht auch ein abgelehntes Promise, sodass ein einziges Seiten-Timeout den ganzen Lauf scheitern lässt.
// @ts-check
// npm install capskip
import {
CapSkip, ApiException, NetworkException, TimeoutException, ValidationException,
} from "capskip";
const ORIGIN = "https://example.com";
const PAGE_URL = `${ORIGIN}/signup`; // the page that shows the widget
const API_URL = `${ORIGIN}/api/signup`; // where the page's own submit sends its JSON
// Local mode. In Server mode, use the address of the PC that runs CapSkip.
const solver = new CapSkip({ host: "127.0.0.1", port: 8080 });
/** @type {Promise<string> | undefined} */
let idRead;
// The captcha_id is the same for every visitor, so read it once per run.
function readCaptchaId() {
idRead ??= (async () => {
const res = await fetch(PAGE_URL, { signal: AbortSignal.timeout(10_000) });
if (!res.ok) throw new Error(`the page answered HTTP ${res.status}`);
const html = await res.text();
const pattern = /captchaId["']?\s*:\s*["']([0-9a-f]{32})["']|[?&]captcha_id=([0-9a-f]{32})/gi;
const ids = new Set([...html.matchAll(pattern)].map((m) => (m[1] ?? m[2]).toLowerCase()));
if (ids.size !== 1) throw new Error(`expected one captcha_id in the page, found ${ids.size}`);
return [...ids][0];
})();
return idRead;
}Auf meiner Mock-Seite kam die ID richtig heraus, wenn die Seite sie mit doppelten Anführungszeichen schrieb, mit einfachen Anführungszeichen und dem Schlüssel in einer eigenen Zeile, als Schlüssel in Anführungszeichen in einem JSON-artigen Objekt und in der Load-URL. Eine Seite mit einer älteren ID in einem Kommentar neben der echten stoppte mit "found 2", und eine Seite, deren Skript die ID anderswo aufbaut, stoppte mit "found 0". Das Muster erwartet 32 hexadezimale Zeichen, wie die IDs in der Dokumentation.
Schritt 3: die fünf Felder mit typisierten Optionen anfordern
Der Aufruf lautet solver.geetestV4(captchaId, url, options). Er sendet eine Aufgabe, fragt das Ergebnis ab und löst sich zu einem Objekt auf. Die API-Dokumentation sagt, res.php sendet die fünf Werte als einen JSON-String in seinem Feld request, weshalb code ein String ist: Das SDK parst ihn ein zweites Mal und kopiert captcha_id, lot_number, pass_token, gen_time und captcha_output auf das Ergebnis, dazu isOffline, wenn GeeTest nicht erreichbar war. Laut SDK-Quellcode lässt ein String, der sich nicht parsen lässt, das Ergebnis unerweitert und löst keinen Fehler aus, daher wirft fiveFields einen Fehler, sofern nicht alle fünf vorhanden sind.
/** @typedef {"slide" | "icon" | "nine" | "word" | "phrase" | "match" | "winlinze" | "svg_seed" | "svg_icon" | "ai"} RiskType */
const NAMES = /** @type {const} */ (["captcha_id", "lot_number", "pass_token", "gen_time", "captcha_output"]);
// All five fields or an error: the SDK hands back an answer it cannot parse untouched.
/** @param {import("capskip").SolveResult} result */
function fiveFields(result) {
/** @type {Record<string, string>} */
const fields = {};
for (const name of NAMES) {
if (!result[name]) {
throw new Error(`the answer has no ${name}; code starts: ${String(result.code).slice(0, 40)}`);
}
fields[name] = String(result[name]);
}
return { fields, offline: result.isOffline === true };
}
/** @param {RiskType} [riskType] */
async function solveOnce(riskType) {
/** @type {import("capskip").GeetestV4Options & { riskType?: RiskType }} */
const options = { timeout: 60, polling_interval: 2 }; // both in seconds
if (riskType) options.riskType = riskType;
const result = await solver.geetestV4(await readCaptchaId(), PAGE_URL, options);
return fiveFields(result);
}Zwei Namen sehen ähnlich aus. captcha_id ist die Widget-ID, die GeeTest zurückspiegelt, und sie ist die, die Sie senden. captchaId ist die ID, die CapSkip der Aufgabe gegeben hat. Das Ergebnis trägt beide, und das SDK-Beispiel gibt captchaId unter der Bezeichnung Captcha ID aus. Auf meinem Mock war die Aufgaben-ID 102, und sie als captcha_id zu senden wurde abgelehnt.
Die Dokumentation nennt zehn Werte für riskType: slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon und ai. GeeTest wendet einen nur an, wo die Website es erlaubt, und die eigene Wahl der Website gewinnt meist, daher konnte ich die Wirkung nicht testen. Die eigene Definition des SDK typisiert riskType als einfachen String, und zur Laufzeit prüft das SDK nur, ob es ein String ist, daher reist ein Tippfehler weiter: Mein Mock erhielt risk_type slid unverändert. Das Typedef RiskType fängt es ab, und tsc wies den Aufruf mit Fehler TS2345 ab. Einen falsch geschriebenen Optionsnamen kann es nicht abfangen, weil der Optionstyp andere Schlüssel erlaubt. Eine Option namens risktype wurde kompiliert, dann lehnte das SDK sie zur Laufzeit als nicht unterstützten Parameter ab.
Die Optionen timeout und polling_interval sind in Sekunden angegeben. Ohne timeout gilt der Client-Standard von 300 Sekunden, und das SDK nimmt kein AbortSignal, setzen Sie also timeout, statt ein Signal zu verwenden: Das Abfragen stoppt damit. Das SDK prüft die Frist nur, wenn die nächste Abfrage fällig ist. Gegen einen Mock, der nie antwortete, endete timeout 5 nach 7,9 Sekunden mit dem Standardintervall von 5 und nach 5,9 mit polling_interval 2. Ein knappes timeout kann auch eine fertige Antwort verlieren, wie die Tabelle unten zeigt. Lassen Sie Raum für die Lösung plus ein Intervall. AsyncCapSkip ist dieselbe Klasse unter einem anderen Namen, da jede Methode schon ein Promise zurückgibt.
Die Option proxy nimmt einen String oder ein Objekt mit type und uri. Bei einem String ist proxytype standardmäßig HTTP, und mein Mock sah die Objektform als proxy-Wert plus proxytype SOCKS5 ankommen. Sie wirkt nur auf die CapSkip-Lösung, und meine fetch-Aufrufe nutzen sie nicht. Die CapSkip-Dokumentation rät über gelegentliche Lösungen hinaus zu einem Proxy-Pool. Ich habe keinen echten Proxy getestet.
Elf Fehler lehnte das SDK mit ValidationException ab, bevor etwas in.php meines Mocks erreichte: keine captcha_id, eine fehlende, relative oder ftp-Seitenadresse, die v3-Parameter gt und challenge, eine Option userAgent, ein unbekannter Optionsname, eine Zahl als riskType, proxytype SOCKS4 und ein Proxy-Objekt ohne uri. Die Ablehnung von userAgent ist wissenswert, weil die Methoden für MTCaptcha und Yandex SmartCaptcha sie akzeptieren und GeeTest v4 nicht. Die Dokumentation sagt, die App antwortet ERROR_BAD_PARAMETERS bei fehlender captcha_id oder nicht unterstütztem proxytype und ERROR_PAGEURL bei fehlender oder fehlerhafter Seitenadresse. Zu den übrigen Ablehnungen sagt die Dokumentation nichts, und das SDK stoppt sie zuerst.
Schritt 4: die fünf Felder als JSON senden
Die CapSkip-Dokumentation sagt, die Felder unter diesen Namen in der Anfrage zu senden, die das eigene Absenden der Seite stellt, unverändert, und für jede Übermittlung erneut zu lösen. Meine Mock-Seite sendet JSON mit der E-Mail und den fünf Feldern, daher macht submit dasselbe. Wenn Ihre Seite ein Formular sendet, ersetzen Sie den Body durch new URLSearchParams und entfernen Sie den Content-Type-Header.
/**
* @param {string} email
* @param {RiskType} [riskType]
*/
async function submit(email, riskType) {
const { fields, offline } = await solveOnce(riskType); // one solve per submission
const res = await fetch(API_URL, {
method: "POST",
// fetch adds no Origin or Referer by itself, and a CSRF check may want them.
headers: { "Content-Type": "application/json", Origin: ORIGIN, Referer: PAGE_URL },
body: JSON.stringify({ email, ...fields }),
signal: AbortSignal.timeout(10_000),
});
const body = (await res.text()).slice(0, 60);
if (!res.ok) throw new Error(`HTTP ${res.status} ${body}`);
return `${email}: HTTP ${res.status}${offline ? " (offline pass)" : ""}`;
}Die beiden Header sind wichtig, weil fetch weder Origin noch Referer hinzufügt. Ohne beide Header beantwortete mein Mock alle sechs Übermittlungen mit 403 und einem csrf-Fehler, nachdem sechs Lösungen verbraucht waren. Mit nur einem der beiden akzeptierte er sie. Das ist die Regel meines Mocks, und Ihre Website hat ihre eigene, senden Sie also vor einem Stapel eine Testübermittlung.
Verwenden Sie eine Antwort nie wieder. Als ich dieselben fünf Felder zweimal sendete, antwortete mein Mock mit 200 und dann mit 403 mit captcha used. Ob GeeTest selbst eine Wiederholung akzeptiert, konnte ich nicht testen.
Das Flag isOffline ist für den Fall, dass GeeTest selbst nicht erreichbar war. Laut Dokumentation besteht das Widget dann ohne Challenge, die Antwort trägt isOffline mit dem Wert true, und die Website entscheidet auf ihrem Server, ob sie sie akzeptiert. Die Einrichtungsanleitung erklärt eine Bezeichnung Offline pass im Tab Monitor, und submit fügt die Wörter offline pass zu seiner Ergebniszeile hinzu. Bei jeder zweiten Antwort offline kamen bei einer Mock-Website, die Offline-Freigaben ablehnt, drei von sechs durch, bei einer, die sie akzeptiert, alle sechs.
Schritt 5: GeeTest v4 in Node.js mit Promise.allSettled
Die Einrichtungsanleitung sagt, dass CapSkip nur so viele Aufgaben eines Typs gleichzeitig löst, wie die Einstellung Max. Threads erlaubt. Die anderen warten bis zu Wait Timeout Sekunden auf einen freien Thread, und das timeout Ihres Aufrufs läuft währenddessen weiter. Die Schleife unten sendet WAVE Übermittlungen, wartet mit Promise.allSettled auf alle und startet die nächste Welle. allSettled lehnt nie ab, daher setzt das Skript den Exit-Code selbst, und describe macht aus jeder der vier SDK-Exception-Klassen eine Zeile.
const WAVE = 3; // keep this at or below Max. Threads for GeeTest in CapSkip
/** @param {unknown} err */
function describe(err) {
if (err instanceof ValidationException) return `refused before sending: ${err.message}`;
if (err instanceof TimeoutException) return `no answer in time: ${err.message}`;
if (err instanceof NetworkException) return `CapSkip not reachable: ${err.message}`;
if (err instanceof ApiException) return `CapSkip error: ${err.message}`;
return err instanceof Error ? err.message : String(err);
}
const emails = [
"[email protected]", "[email protected]", "[email protected]",
"[email protected]", "[email protected]", "[email protected]",
];
/** @type {PromiseSettledResult<string>[]} */
const settled = [];
for (let i = 0; i < emails.length; i += WAVE) {
const wave = emails.slice(i, i + WAVE).map((email) => submit(email));
settled.push(...(await Promise.allSettled(wave)));
}
settled.forEach((s, i) => {
console.log(s.status === "fulfilled" ? `ok ${s.value}` : `FAIL ${emails[i]}: ${describe(s.reason)}`);
});
process.exitCode = settled.every((s) => s.status === "fulfilled") ? 0 : 1;Prüfen Sie die Typen und führen Sie es dann aus. Es gibt eine Zeile pro E-Mail aus.
# Check the types, then run the script npx tsc node geetest_v4.mjs
Diese Zeilen sind Mock-Ergebnisse von Node.js 24.22.0 unter Windows 11 mit capskip 1.8.0, gemessen vom Prozessstart bis zum Ende. Die Anzahlen stimmten auf 20.11.1 und 25.2.1 überein, und die Zeiten wichen um höchstens 0,3 Sekunden ab.
| Mock-Einstellung | Was das Skript tat |
|---|---|
| Sechs Übermittlungen, Lösung 2 Sekunden, 3 Slots; WAVE 3, 6 oder 1 | In jedem Fall sechs, in 7,7 s, 5,9 s und 22,9 s; höchstens 3, 3 und 1 Aufgabe gleichzeitig |
| Aufruf-timeout 4, polling_interval 1, Lösung 2 Sekunden, 3 Slots; WAVE 3 oder 6 | WAVE 3: sechs durch, 5,7 Sekunden. WAVE 6: drei durch, drei "timeout 4 exceeded" bei 4,9 |
| Lösung 2 Sekunden, timeout 3; polling_interval 2 oder 1 | 2: alle drei "timeout 3 exceeded" nach 3,9 Sekunden. 1: alle drei durch, 2,9 Sekunden |
| Antwort nie bereit, timeout 5; polling_interval 5, 2 oder 1 | TimeoutException nach 7,9 s, 5,9 s und 5,9 s |
| Header Origin und Referer entfernt | Sechs mit 403 csrf abgelehnt, nachdem sechs Lösungen verbraucht waren |
| Dieselben fünf Felder zweimal gesendet | 200, dann 403 "captcha used" |
| Jede zweite Antwort offline; die Website lehnt Offline-Freigaben ab oder akzeptiert sie | Drei durch und drei abgelehnt, oder alle sechs durch |
| Die Antwort ist kein JSON, oder lot_number fehlt | Sechs Absicherungsfehler und keine Anfrage an die Website |
| Die ersten beiden Aufgaben enden in ERROR_CAPTCHA_UNSOLVABLE | Zwei FAIL-Zeilen, vier durch |
Wellen kosten Zeit, wenn das Timeout großzügig ist: Sechs Übermittlungen auf einmal brauchten 5,9 Sekunden gegen 7,7 bei Wellen von drei, weil eine Welle auf ihr langsamstes Mitglied wartet, bevor die nächste startet. Sie zahlen sich aus, wenn das Aufruf-Timeout knapp ist, wie die zweite Zeile zeigt. Bei einem Timeout von 4 Sekunden liefen die drei Aufgaben, die hinter vollen Slots anstanden, aus der Zeit. Die dritte Zeile ist die verlorene Antwort: Der Mock hatte sie bei 2 Sekunden bereit, aber die letzte Abfrage kam bei 1,8 Sekunden und die nächste war bei 3,8 fällig, nach der Frist. Halten Sie WAVE auf oder unter dem Wert Max. Threads der GeeTest-Zeile in CapSkip.
Häufige Fehler
Sofern eine Zeile nicht gesehen angibt, stammt sie von CapSkip, genauer aus der GeeTest-v4-API-Dokumentation.
| Fehler | Ursache | Beheben |
|---|---|---|
| ValidationException | Im SDK abgelehnt, nichts gesendet (gesehen, elf Fälle) | Lesen Sie die Nachricht |
| ERROR_BAD_PARAMETERS | Laut Dokumentation: keine captcha_id oder ein proxytype, der nicht akzeptiert wird | Das SDK lehnt beides zuerst ab |
| ERROR_PAGEURL | Laut Dokumentation: Die Seitenadresse fehlt oder ist fehlerhaft | Übergeben Sie die vollständige Seitenadresse |
| ERROR_PROXY_FORMAT | Laut Dokumentation: ein proxy-Wert, den CapSkip nicht parsen kann | Verwenden Sie IP:PORT oder login:password@IP:PORT |
| ERROR_CAPTCHA_UNSOLVABLE | Laut Dokumentation: Die Aufgabe konnte nicht gelöst werden. Mein Mock erzeugte das bei zwei Aufgaben | Führen Sie die fehlgeschlagenen E-Mails erneut aus |
| ERROR_KEY_DOES_NOT_EXIST | API Key Validation ist eingeschaltet. Ohne apiKey sendete das SDK den Schlüssel capskip, und mein Mock lehnte ihn ab | Übergeben Sie Ihren Key als apiKey |
| TimeoutException | Keine Antwort innerhalb von timeout (gesehen) | Erhöhen Sie timeout oder senken Sie polling_interval |
| NetworkException | connect ECONNREFUSED, wenn nichts lauschte (gesehen) | Starten Sie CapSkip, prüfen Sie host und port |
| HTTP 403 von der Website | Die eigene Regel der Website: Header, eine verbrauchte Antwort oder eine Offline-Freigabe | Vergleichen Sie mit der eigenen Anfrage der Seite |
FAQ
Kann ich das Skript auf einem anderen PC als CapSkip ausführen?
Ja. Stellen Sie CapSkip in den Server mode und setzen Sie die Option host auf die Adresse seines PCs, was die einzige Zeile ist, die sich ändert. Die Einrichtungsanleitung weist darauf hin, dass der Server mode Administratorrechte braucht. Mein Rat, keine Aussage der Einrichtungsanleitung: Gehen Sie davon aus, dass der Port im Server mode für jede Adresse offen ist, fügen Sie eine Windows-Firewall-Blockregel für die Rechner hinzu, die Sie nicht erwarten, und schalten Sie API Key Validation ein, damit jeder Aufruf einen Schlüssel tragen muss.
Kann eine Lösung mehrere Übermittlungen bedienen?
Nein. Die Dokumentation sagt, für jede Übermittlung erneut zu lösen, und mein Mock lehnte eine Wiederholung ab.
Funktioniert das auf einer Seite, die gt und eine challenge ausgibt?
Nein, das ist GeeTest v3, und das SDK lehnt gt und challenge in einem v4-Aufruf ab. Für diese Generation folgen Sie der GeeTest-v3-Anleitung für Node.js.
GeeTest v4 in Node.js besteht aus einer pro Lauf gelesenen ID, einer Lösung pro Übermittlung und fünf unter ihren eigenen Namen kopierten Feldern. Eine abgelehnte Übermittlung oder eine zweite Lösung landet nie auf einer Rechnung, da CapSkip ein lokaler Captcha-Löser ist, der auf Ihrem eigenen PC läuft. Die Node.js-Captcha-Solver-Seite listet die anderen Captcha-Typen auf.
