puppeteer-cluster и капча: решайте с одним токеном на задачу

Чтобы решить капчу в puppeteer-cluster, вызывайте решатель внутри функции задачи и держите токен в локальной константе. Токен reCAPTCHA работает один раз, поэтому один токен, общий для нескольких задач, пройдёт только одну форму. Это руководство строит такой скрипт на пакете capskip для Node.js, который общается с приложением CapSkip на вашем собственном ПК с Windows по фиксированной лицензии, а затем задаёт три лимита: maxConcurrency, таймаут кластера и retryLimit. Версия для одной страницы описана на странице сервиса распознавания капчи для Puppeteer.
Что понадобится
- CapSkip, запущенный на ПК с Windows, доступен по хосту и порту (по умолчанию 127.0.0.1 и 8080). Server mode заставляет его слушать ваш сетевой или публичный IP, поэтому кластер на другом ПК может использовать тот же решатель. Настройки подключения позволяют переключаться между этими двумя режимами.
- Node.js 22.12 или новее для Puppeteer 25.17.0 (поле engines в его package.json) либо Node.js 18 или новее для Puppeteer 24.43.1. Я запускал Node 24.22.0 и 25.2.1 с первым и Node 20.11.1 и 24.22.0 со вторым, а Node 18 и 22 не запускал.
- puppeteer-cluster 0.25.0 (поля engines нет, допустимый диапазон peer: Puppeteer 24.0.0 или новее) и capskip 1.7.0 (Node 18 или новее), то есть версии, которые я запускал.
- Страница, которую вам можно автоматизировать, с флажком reCAPTCHA v2.
Проверьте, насколько недавно выпускалась библиотека. Когда я проверял в ноябре 2026 года, последним выпуском была 0.25.0 (13 ноября 2025 года), в master не было более новых коммитов, а открытыми оставались 112 issues и 16 pull request. Библиотека не в архиве, а README puppeteer-cluster покажет, подходит ли вам такой темп.
Как тестировался скрипт puppeteer-cluster для капчи: не на настоящем приложении CapSkip и не на настоящей странице reCAPTCHA. Каждый запуск использовал написанную мной имитацию in.php и res.php, а также сайт-заменитель с формой: div g-recaptcha, атрибутом data-sitekey и скрытой textarea с именем g-recaptcha-response. Это не виджет Google. Правила мои: один токен на одно использование, токен должен соответствовать sitekey своей страницы, а форме нужен её cookie CSRF. Имитация также отклоняет sitekey, не проходящий правило формы, которое я прочитал в исходном коде приложения CapSkip. Большинство запусков использовало Chrome for Testing 156.0.8078.47 через PUPPETEER_EXECUTABLE_PATH, а блок установки в том виде, как он написан, работал и с Chrome, который скачивает npm (157.0.8103.50 для Puppeteer 25.17.0, 148.0.7778.97 для 24.43.1). npm 11 предупреждает, что у [email protected] есть скрипт установки, ещё не охваченный allowScripts, но загрузка всё равно прошла. При отключённых скриптах установки скрипт останавливается с Could not find Chrome.
Пишем скрипт
Шаг 1: создайте проект и настройки
Сначала создайте package.json: с npm 11.19.1 в Windows папка без него получила свои пакеты в родительской папке.
# 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
В Node.js от 18 до 22.11 вместо этой команды используйте npm install puppeteer@24 puppeteer-cluster capskip Так нужно потому, что строка выше на Node 20.11.1 установила Puppeteer 25.17.0 с предупреждениями EBADENGINE, и скрипт затем падал с ERR_REQUIRE_ESM.
Далее начните файл с именем cluster-solve.js. Этот блок и блоки в шагах с 2 по 4 помещаются в него по порядку, и ничего не запускается до последнего. SDK сам не читает ни одну переменную CAPSKIP, поэтому скрипт читает из них хост и порт сам.
// 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 throwingШаг 2: решайте внутри задачи
Каждая задача загружает свою страницу, читает sitekey, запрашивает у CapSkip токен для адреса этой страницы, записывает его в скрытую textarea и нажимает отправку. На настоящей странице эта textarea появляется, когда скрипт от Google отрисует виджет, что обычно покрывается временем решения; я тестировал только статическую. Если ваш сайт объявляет data-callback, вызовите его после записи токена; у моего заменителя его нет, поэтому я это не проверял. Проверка статуса 200 подходит только заменителю; настоящие сайты часто снова показывают форму с ошибкой при 200. В руководстве по reCAPTCHA v2 в Node.js разобран сценарий для одной страницы.
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);
}Шаг 3: повторяйте только то, что повтор может исправить
retryLimit повторяет каждую ошибку, которую бросает задача, поэтому эта обёртка сначала проверяет тип ошибки. ApiException с ERROR_CAPTCHA_UNSOLVABLE означает, что CapSkip не смог решить эту задачу, и новая может сработать. Любое другое ApiException и любое ValidationException происходят из вашего запроса или ваших лимитов, поэтому обёртка записывает их и завершает задачу. При настройках по умолчанию CapSkip сразу отклоняет отсутствующий или неверно сформированный sitekey (ERROR_GOOGLEKEY в документации API), что заканчивается в обёртке; настройка, которая перечисляет задания с неверными данными, по умолчанию выключена. Обёртка не повторяет отказ из-за нехватки слота, потому что кластер немедленно повторил бы запрос в ту же полную очередь: лучше уменьшите maxConcurrency вместо этого. В исходном коде приложения, который я читал, правильно сформированный ключ, не подходящий странице, получает ответ unsolvable, поэтому его повторяют, пока retryLimit не исчерпан.
// 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 });
}
}Шаг 4: запустите кластер и поставьте страницы в очередь
Chrome по умолчанию запускается без окна (headless), как я видел в командной строке запущенного браузера.
(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
На имитации восемь форм, три страницы и решение на имитации за 2 секунды дали 8 принятых форм из 8 и не более 3 одновременных решений. Решение заняло 3.8 секунды от отправки до токена, а не 2, потому что SDK опрашивает на 0, 0.25, 0.75, 1.75 и 3.75 секунде. Остальные конфигурации среды выполнения дали то же самое, без предупреждений в логе.
Почему токен puppeteer-cluster для капчи остаётся внутри задачи
Соблазнительный короткий путь: одна переменная над функцией задачи, схема, которую скрипт опускает.
// 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);
}На имитации шесть форм дали 3 решения, 3 принятые формы и 6 отказов, считая повторы. Первые три задачи видят пустую переменную и проходят. Каждая следующая задача использует последний сохранённый токен, который принадлежит другому sitekey или уже использован. Скрипт в написанном виде сделал 8 решений на 8 форм без отказов.
Другая ловушка касается cookie jar. Режим по умолчанию, CONCURRENCY_CONTEXT, даёт каждой задаче собственный приватный контекст браузера, а CONCURRENCY_PAGE делит один на всех. Мой заменитель ставит новый cookie CSRF при каждой загрузке страницы, поэтому задачи, загрузившиеся раньше, падают. Восемь форм потребовали от 12 до 14 решений, от 5 до 8 отказов по CSRF и от 6 до 7 принятых форм за 10 запусков. Сайт со стабильным cookie не сломался бы.
Три лимита, которые должны согласоваться
В скрипте puppeteer-cluster для капчи параметр puppeteer-cluster maxConcurrency ограничивает число решений в работе, потому что каждая задача делает одно, а 0 означает отсутствие лимита. У CapSkip есть собственный лимит: настройка "Max. Threads" в строке reCAPTCHA в Settings, по умолчанию 10. Лишние задачи ждут в его очереди до "Wait Timeout" (по умолчанию 250 секунд), и таймаут SDK включает это ожидание. На имитации с двумя слотами решения и четырьмя страницами решение на 4 секунды заняло 7.8 секунды от отправки до токена без ожидания и 12.8 с ожиданием слота, потому что SDK забирает токен при первой проверке после окончания решения, а проверяет он примерно на 3.8, 7.8 и 12.8 секунде. Очередь к тому же короткая. В changelog сказано, что начиная с CapSkip 2.4.0 задача reCAPTCHA, пришедшая в полную очередь, отклоняется с ошибкой нехватки слота, а в исходном коде приложения, который я читал, очередь такой же глубины, как "Max. Threads". Моя имитация применяет это правило: с двумя слотами решения, очередью из двух и восемью страницами сразу 4 формы были приняты, а 4 сдались с ERROR_NO_SLOT_AVAILABLE, тогда как четырёх страниц хватало на 8 из 8. Держите maxConcurrency не выше "Max. Threads" и помните, что два кластера на одном CapSkip делят этот лимит. Каждое решение в работе занимает и IP-адрес, а руководство по настройке советует дать CapSkip прокси не меньше, чем "Max. Threads".
Таймаут puppeteer-cluster должен превышать ожидание SDK плюс работу со страницей. Значение кластера по умолчанию 30 секунд, а SDK ждёт 300 для reCAPTCHA, если вы не зададите recaptchaTimeout. Если убрать параметр timeout и взять решение на имитации в 40 секунд, строка Timeout hit: 30000 появилась примерно через 31 секунду после запуска скрипта, но процесс завершился примерно на 44-й, потому что брошенная задача продолжала опрашивать. Лимит SDK в 3 секунды сработал на 3.8 секунды, потому что SDK смотрит на свой дедлайн только между опросами.
Таймаут не останавливает решение. На имитации, при решении в 12 секунд, четырёх формах, двух страницах и одном повторе, таймаут кластера в 5 секунд дал 8 решений на 4 формы, до 6 в работе на 2 страницы и 8 токенов, доставленных задачам, которые уже упали. Ожидание SDK в 3 секунды при таймауте кластера в 9 дало timeout 3 exceeded и всё равно 8 решений. Бросает ли настоящий CapSkip решение, которое никто не опрашивает, здесь не измерено. В руководстве по настройке сказано, что решение, которое переживает свой "Row Timeout" (250 секунд для reCAPTCHA), останавливается, а в исходном коде приложения, который я читал, я не нашёл кода, отменяющего задание, когда опрос прекращается (прочитано, не запускалось).
Ошибки, retryLimit и тихие сбои
Параметр puppeteer-cluster retryLimit считает дополнительные попытки: 1 означает две попытки, 2 означает три. Страница, которую имитация один раз отклонила как unsolvable, была принята при повторе, а при retryLimit 0 она упала, и код выхода был 1.
Без шага 3 ошибки, которые повтор исправить не может, всё равно повторяются. При retryLimit 2 неверно сформированный sitekey занял три попытки, как и неподдерживаемый параметр, о котором SDK сообщает как о ValidationException. С обёрткой каждый занял одну. Правильно сформированный ключ, который имитация всегда считала нерешаемым, всё равно занял все три.
cluster.execute() пропускает правила повторов, которые retryLimit задаёт: на странице с однократным unsolvable при retryLimit 2 он отклонился после одной попытки, тогда как cluster.queue() повторял. Неудачная задача в очереди тоже молчит: без слушателя taskerror и без переменной DEBUG неудачный запуск печатал только итог. Если задать DEBUG=puppeteer-cluster:log печаталась строка на каждый сбой.
| Что вы видите | Причина | Исправить |
|---|---|---|
Timeout hit: 30000 | Кластер по умолчанию завершил задачу, пока CapSkip ещё решал | Задайте таймаут кластера выше ожидания SDK |
timeout 90 exceeded | SDK перестал ждать токен | Замерьте решения на своём ПК, затем поднимите оба таймаута |
ERROR_GOOGLEKEY | Sitekey отсутствует или не похож на ключ reCAPTCHA | Проверьте селектор, читающий sitekey; не повторяйте |
ERROR_NO_SLOT_AVAILABLE | В CapSkip пришло больше задач, чем вмещает его очередь | Установить maxConcurrency не выше "Max. Threads" |
ERROR_PAGEURL | Адрес страницы отсутствует или не является адресом http или https | Передайте адрес загруженной страницы; не повторяйте |
connect ECONNREFUSED 127.0.0.1:12999 | На этом порту никто не слушает | Запустите CapSkip и проверьте хост и порт |
| Сайт отклоняет большинство отправок (мой заменитель отвечает 403; ваш может ответить 200 со страницей ошибки) | Общий токен или общий cookie jar | Держите токен локальным; используйте режим по умолчанию |
Использование CapSkip на сервере
Скрипту puppeteer-cluster для капчи нужны только хост и порт. Local mode слушает 127.0.0.1, поэтому кластер должен работать на этом ПК. Server mode слушает ваш сетевой или публичный IP, и вы задаёте CAPSKIP_HOST для этого ПК с Windows. Я тестировал только 127.0.0.1. При запуске Server mode CapSkip разрешает свой порт с любого адреса, а собственное разрешающее правило это не сузит, поэтому добавьте правило блокировки брандмауэра Windows для адресов, которые должны остаться снаружи.
FAQ
Работает ли puppeteer-cluster с текущим Puppeteer?
Скрипт запускался на Puppeteer 25.17.0 и 24.43.1. Если вы предпочитаете не управлять пулом сами, в руководстве по Crawlee разобран краулер со своей конкурентностью и повторами.
Можно ли сначала решить все страницы, а кластер запустить потом?
Небезопасно. В документации по проверке reCAPTCHA сказано, что токен живёт две минуты и работает один раз, поэтому токен, полученный до того, как задача доберётся до свободной страницы, может устареть. Запрашивайте токен внутри задачи, как это делает скрипт.
Коротко
Скрипт puppeteer-cluster для капчи сводится к одному решению на задачу, токену в локальной константе и согласованным лимитам: maxConcurrency не выше того, что CapSkip решает одновременно, таймауту кластера длиннее ожидания SDK и повторам только для ошибок, которые повтор может исправить. CapSkip обеспечивает локальное распознавание капчи по фиксированной лицензии, поэтому повтор стоит времени на вашем собственном ПК и не стоит платы за решение. Тот же пакет решает не только reCAPTCHA, а на странице сервиса распознавания капчи для Node.js показано, какие типы.
