GeeTest v4 на Node.js: пакетные регистрации с fetch и типами

Чтобы решить GeeTest v4 на Node.js без браузера, прочитайте captcha_id со страницы один раз, вызовите solver.geetestV4() из пакета capskip с этим идентификатором и адресом страницы и отправьте пять возвращённых полей под теми же именами в запросе, который страница делает сама. Скрипт ниже делает это для шести регистраций со встроенным fetch, с одним новым решением на каждую отправку, и завершается Promise.allSettled. Задачи решает сервис CapSkip для GeeTest v4 на вашем собственном ПК с Windows, без платы за каждое решение.
Что понадобится
- Машина с Windows и CapSkip 5.0.0 или новее, первый выпуск, который решает GeeTest v4, по журналу изменений.
- Node.js 18 или новее, как заявлено в поле engines у capskip 1.8.0. Это первая версия SDK с geetestV4(). Мои запуски охватывали 20.11.1, 24.22.0 и 25.2.1, так что сам Node.js 18 я не запускал.
- TypeScript, но только для необязательной проверки типов. На момент написания npm разрешал typescript 7.0.2, который заявляет Node.js 16.20 или новее, и @types/node 26.6.6.
- Страница регистрации или входа с виджетом GeeTest v4, которую вам разрешено автоматизировать.
- Адрес для CapSkip. Local mode оставляет его на 127.0.0.1. Server mode принимает подключения и из вашей сети, или с публичного IP, а оба режима описывает руководство по настройке в разделе Connection Settings.
Все запуски ниже использовали два небольших сервера, которые я написал: один изображает API CapSkip, другой изображает страницу регистрации, поэтому правила сайта мои. Настоящее приложение CapSkip в момент тестирования на этом ПК не отвечало, поэтому я ничего ему не отправлял, и ни один сайт GeeTest не видел запроса. Где утверждение опирается на документацию CapSkip, исходный код SDK или документацию GeeTest, а не на запуск, я это указываю. Настоящий сайт проверяет пять полей на своём сервере приватным ключом через серверный API проверки GeeTest.
Шаг 1: подготовьте папку
Запустите первый блок в пустой папке. Он создаёт package.json, устанавливает capskip и добавляет TypeScript для проверки типов. Сохраните блок tsconfig как tsconfig.json. Затем сохраните четыре блока JavaScript из шагов с 2 по 5 по порядку как один файл geetest_v4.mjs. Расширение .mjs разрешает top-level await. Перед первым запуском замените ORIGIN, два пути и адреса email на свои. Если оставить как есть, скрипт обращается к example.com и останавливается с сообщением "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"]
}С этим файлом tsc читает скрипт как типизированный JavaScript. Пакет поставляет GeetestV4Options и SolveResult, у которого пять полей GeeTest необязательны, поэтому в шаге 3 есть проверка.
Шаг 2: прочитайте captcha_id один раз
Страница передаёт идентификатор в initGeetest4 как captchaId, а запрос к gcaptcha4.geetest.com/load несёт его как captcha_id. Об этом сказано здесь: Документация API GeeTest v4. Он одинаков для всех посетителей, поэтому readCaptchaId держит свой promise в переменной и загружает страницу один раз за запуск, сколько бы отправок ни следовало. Он собирает все совпадения в Set и не гадает: два разных идентификатора или ни одного приводят к тому, что каждая отправка завершается ошибкой до покупки любого решения. Он также кэширует отклонённый promise, поэтому один тайм-аут страницы проваливает весь запуск.
// @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;
}На моей странице имитации идентификатор определялся верно, когда страница писала его с двойными кавычками, с одинарными кавычками и ключом на отдельной строке, как ключ в кавычках в объекте в стиле JSON и в адресе load. Страница со старым идентификатором, оставленным в комментарии рядом с настоящим, остановилась с сообщением "found 2", а страница, чей скрипт строит идентификатор в другом месте, остановилась с "found 0". Шаблон ожидает 32 шестнадцатеричных символа, как у идентификаторов в документации.
Шаг 3: запросите пять полей с типизированными параметрами
Вызов выглядит так: solver.geetestV4(captchaId, url, options). Он отправляет задание, опрашивает результат и разрешается объектом. В документации API сказано, что res.php присылает пять значений одной строкой JSON в поле request, поэтому code является строкой: SDK разбирает её второй раз и копирует captcha_id, lot_number, pass_token, gen_time и captcha_output в результат, плюс isOffline, когда GeeTest был недоступен. Согласно исходному коду SDK, строка, которая не разбирается, оставляет результат нераскрытым и не вызывает ошибки, поэтому fiveFields выбрасывает исключение, если не все пять значений на месте.
/** @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);
}Два имени похожи. captcha_id является идентификатором виджета, который GeeTest возвращает эхом, и отправлять нужно его. captchaId является идентификатором, который CapSkip присвоил заданию. Результат несёт оба, а пример SDK печатает captchaId с подписью Captcha ID. На моей имитации идентификатор задания был 102, и его отправка как captcha_id была отклонена.
В документации перечислено десять значений riskType: slide, icon, nine, word, phrase, match, winlinze, svg_seed, svg_icon и ai. GeeTest применяет одно из них, только если сайт это позволяет, и выбор самого сайта обычно побеждает, поэтому проверить эффект я не мог. Собственное определение SDK типизирует riskType как обычную строку, а во время выполнения SDK проверяет лишь то, что это строка, так что опечатка проходит дальше: моя имитация получила risk_type slid без изменений. Typedef RiskType её ловит, и tsc отклонил вызов с ошибкой TS2345. Он не может поймать неверно написанное имя параметра, потому что тип параметров допускает другие ключи. Параметр с именем risktype скомпилировался, а затем SDK отклонил его во время выполнения как неподдерживаемый.
Параметры timeout и polling_interval задаются в секундах. Без timeout действует значение клиента по умолчанию, 300 секунд, а SDK не принимает AbortSignal, поэтому задавайте timeout вместо гонки с сигналом: опрос останавливается вместе с ним. SDK проверяет срок только когда подходит следующий опрос. На имитации, которая никогда не отвечала, timeout 5 завершился через 7.9 секунды при интервале по умолчанию 5 и через 5.9 при polling_interval 2. Слишком жёсткий timeout может также потерять готовый ответ, как показывает таблица ниже. Оставьте запас на решение плюс один интервал. AsyncCapSkip является тем же классом под другим именем, потому что каждый метод и так возвращает promise.
Параметр proxy принимает строку или объект с type и uri. Со строкой proxytype по умолчанию равен HTTP, и моя имитация увидела объектную форму как значение proxy плюс proxytype SOCKS5. Он влияет только на решение CapSkip, а мои вызовы fetch его не используют. В документации CapSkip советуют пул прокси при чём-то большем, чем разовые решения. Настоящий прокси я не тестировал.
Одиннадцать ошибок SDK отклонил с ValidationException до того, как что-либо дошло до in.php моей имитации: нет идентификатора капчи, отсутствующий, относительный или ftp-адрес страницы, параметры v3 gt и challenge, параметр userAgent, неизвестное имя параметра, число в качестве riskType, proxytype SOCKS4 и объект proxy без uri. Отказ по userAgent стоит запомнить, потому что методы MTCaptcha и Yandex SmartCaptcha его принимают, а GeeTest v4 нет. В документации сказано, что приложение отвечает ERROR_BAD_PARAMETERS на отсутствующий captcha_id или неподдерживаемый proxytype и ERROR_PAGEURL на отсутствующий или неверно сформированный адрес страницы. Про остальные отказы в документации ничего нет, а SDK останавливает их первым.
Шаг 4: отправьте пять полей как JSON
В документации CapSkip сказано отправлять поля под этими именами в запросе, который делает собственная отправка страницы, без изменений и решать заново для каждой отправки. Моя страница имитации отправляет JSON с email и пятью полями, поэтому submit делает то же самое. Если ваша страница отправляет форму, замените тело на new URLSearchParams и уберите заголовок типа содержимого.
/**
* @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)" : ""}`;
}Два заголовка важны, потому что fetch не добавляет ни Origin, ни Referer. Без обоих заголовков моя имитация ответила на все шесть отправок 403 и ошибкой csrf, после того как шесть решений уже было потрачено. С одним из двух она их принимала. Это правило моей имитации, а у вашего сайта свои, поэтому перед пакетом отправьте одну пробную отправку.
Никогда не используйте ответ повторно. Когда я отправил те же пять полей дважды, моя имитация ответила 200, а затем 403 с captcha used. Принимает ли сам GeeTest повтор, я проверить не мог.
Флаг isOffline нужен на случай, когда сам GeeTest был недоступен. В документации сказано, что тогда виджет проходит без задания, ответ несёт isOffline со значением true, а принимать ли его, сайт решает на своём сервере. Руководство по настройке объясняет метку Offline pass на вкладке Monitor, а submit добавляет слова offline pass в строку результата. Когда каждый второй ответ офлайн, имитация сайта, отклоняющая офлайн-пропуски, приняла три из шести, а принимающая их приняла все шесть.
Шаг 5: GeeTest v4 на Node.js с Promise.allSettled
Руководство по настройке говорит, что CapSkip решает одновременно столько задач одного типа, сколько позволяет настройка Max. Threads. Остальные ждут свободный поток до Wait Timeout секунд, а ваш тайм-аут вызова всё это время продолжает идти. Цикл ниже отправляет WAVE отправок, ждёт их все через Promise.allSettled и запускает следующую волну. allSettled никогда не отклоняется, поэтому скрипт сам задаёт код выхода, а describe превращает каждый из четырёх классов исключений SDK в одну строку.
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;Проверьте типы, затем запустите. Он печатает одну строку на каждый email.
# Check the types, then run the script npx tsc node geetest_v4.mjs
Эти строки являются результатами имитации на Node.js 24.22.0 на Windows 11 с capskip 1.8.0, засечёнными от запуска процесса до выхода. Количества совпали на 20.11.1 и 25.2.1, а времена согласовались в пределах 0.3 секунды.
| Настройка имитации | Что сделал скрипт |
|---|---|
| Шесть отправок, решение 2 секунды, 3 слота; WAVE 3, 6 или 1 | Шесть в каждом случае, за 7.7, 5.9 и 22.9 секунды; не более 3, 3 и 1 задания одновременно |
| Тайм-аут вызова 4, polling_interval 1, решение 2 секунды, 3 слота; WAVE 3 или 6 | WAVE 3: шесть принято, 5.7 секунды. WAVE 6: три принято, три "timeout 4 exceeded" на 4.9 |
| Решение 2 секунды, timeout 3; polling_interval 2 или 1 | 2: все три "timeout 3 exceeded" на 3.9 секунды. 1: все три приняты, 2.9 секунды |
| Ответ никогда не готов, timeout 5; polling_interval 5, 2 или 1 | TimeoutException через 7.9, 5.9 и 5.9 секунды |
| Заголовки Origin и Referer убраны | Шесть отклонено с 403 csrf, после того как шесть решений потрачено |
| Те же пять полей, отправленные дважды | 200, затем 403 "captcha used" |
| Каждый второй ответ офлайн; сайт отклоняет или принимает офлайн-пропуски | Три приняты и три отклонены, или все шесть приняты |
| Ответ не JSON или отсутствует lot_number | Шесть ошибок проверки и ни одного запроса к сайту |
| Первые два задания завершаются ERROR_CAPTCHA_UNSOLVABLE | Две строки FAIL, четыре приняты |
Волны стоят времени, когда тайм-аут щедрый: шесть отправок сразу заняли 5.9 секунды против 7.7 для волн по три, потому что волна ждёт самого медленного участника, прежде чем начнётся следующая. Они окупаются, когда тайм-аут вызова жёсткий, как показывает вторая строка. При тайм-ауте 4 секунды три задания, которые встали в очередь, когда все слоты были заняты, не уложились во время. Третья строка показывает потерянный ответ: в имитации он был готов на 2 секунде, но последний опрос пришёл на 1.8 секунды, а следующий должен был прийти на 3.8, после срока. Держите WAVE не выше значения Max. Threads в строке GeeTest в CapSkip.
Частые ошибки
Если в строке не указано «воспроизведено», она взята отсюда: Документация API GeeTest v4.
| Ошибка | Причина | Исправить |
|---|---|---|
| ValidationException | Отклонено внутри SDK, ничего не отправлено (воспроизведено, одиннадцать случаев) | Прочитайте сообщение |
| ERROR_BAD_PARAMETERS | По документации: нет captcha_id или proxytype, который не принимается | SDK отклоняет оба первым |
| ERROR_PAGEURL | По документации: адрес страницы отсутствует или неверно сформирован | Передайте полный адрес страницы |
| ERROR_PROXY_FORMAT | По документации: значение прокси, которое CapSkip не может разобрать | Используйте IP:PORT или login:password@IP:PORT |
| ERROR_CAPTCHA_UNSOLVABLE | По документации: задание не удалось решить. Моя имитация вызвала это для двух заданий | Запустите неудавшиеся email заново |
| ERROR_KEY_DOES_NOT_EXIST | API Key Validation включена. Без apiKey SDK отправил ключ capskip, и моя имитация его отклонила | Передайте свой ключ как apiKey |
| TimeoutException | Нет ответа в пределах timeout (воспроизведено) | Увеличьте timeout или уменьшите polling_interval |
| NetworkException | connect ECONNREFUSED, когда никто не слушал (воспроизведено) | Запустите CapSkip, проверьте host и port |
| HTTP 403 от сайта | Собственное правило сайта: заголовки, использованный ответ или офлайн-пропуск | Сравните с собственным запросом страницы |
FAQ
Можно ли запускать скрипт на другом ПК, не на том, где CapSkip?
Да. Переведите CapSkip в Server mode и задайте параметр host равным адресу его ПК, это единственная строка, которая меняется. В руководстве по настройке отмечено, что Server mode требует прав администратора. Мой совет, а не утверждение руководства: считайте, что в Server mode порт открыт для всех адресов, добавьте блокирующее правило Windows Firewall для машин, которых вы не ждёте, и включите API Key Validation, чтобы каждый вызов нёс ключ.
Может ли одно решение обслужить несколько отправок?
Нет. В документации сказано решать заново для каждой отправки, и моя имитация отклонила повтор.
Работает ли это на странице, которая выдаёт gt и challenge?
Нет, это GeeTest v3, и SDK отклоняет gt и challenge в вызове v4. Для того поколения следуйте руководству по GeeTest v3 для Node.js.
GeeTest v4 на Node.js сводится к одному идентификатору за запуск, одному решению на каждую отправку и пяти полям, скопированным под их собственными именами. Отклонённая отправка или второе решение никогда не попадает в счёт, потому что локальный сервис распознавания капчи работает на вашем ПК. На странице сервиса распознавания капчи для Node.js перечислены остальные типы CAPTCHA.
