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

puppeteer-cluster captcha - puppeteer-cluster CAPTCHA: Solve It With One Token Per Task

Чтобы решить капчу в 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 exceededSDK перестал ждать токенЗамерьте решения на своём ПК, затем поднимите оба таймаута
ERROR_GOOGLEKEYSitekey отсутствует или не похож на ключ 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 показано, какие типы.