Skip to content

Модуль Node.js для решения капчи в Puppeteer ​

Модуль capguru решает капчу прямо на странице, которой управляет ваш скрипт на Puppeteer: кликает по картинкам, перетаскивает ползунок и проходит другие задания, а тип капчи на странице умеет определять сам. Начиная с версии 0.5.0 он также получает токены reCAPTCHA и Cloudflare Turnstile, распознаёт текстовые капчи и работает без браузера.

Проверить скрипт можно на демо-страницах капч. Если вы пишете на Python, есть такой же модуль для Python для Playwright и Selenium.

Версии ​

Версия модуляСкачатьИзменения
0.5.0npm · 0.5Токены reCAPTCHA v2/v3 (Enterprise) и Cloudflare Turnstile, текстовые капчи, клиент без браузера, таймауты и CapGuruSolveError и другое
0.40.4Автоопределение капчи auto(), добавлен AWS WAF

Установка ​

Модуль опубликован на npm:

bash
npm install capguru puppeteer
javascript
const { CaptchaSolver, CapGuruFatalError, CapGuruSolveError } = require('capguru');

Обновление до последней версии:

bash
npm install capguru@latest
Установка без npm

Скачайте архив из таблицы версий, скопируйте папку capguru в свой проект и установите Puppeteer:

bash
npm install puppeteer

Подключайте модуль по относительному пути: require('./capguru').

Как использовать ​

  1. Импортируйте CaptchaSolver из пакета.
  2. Запустите браузер, как в примере ниже, и создайте солвер до перехода на страницу с капчей, затем вызовите await solver.setup().
  3. Откройте страницу и вызовите await solver.auto(): модуль сам найдёт капчу и решит её.

Если тип капчи известен заранее, можно вызвать нужный метод напрямую.

javascript
const puppeteer = require('puppeteer');
const { CaptchaSolver, CapGuruFatalError } = require('capguru');

(async () => {
  const browser = await puppeteer.launch({
    headless: false,
    ignoreDefaultArgs: ['--enable-automation'],
    args: ['--disable-blink-features=AutomationControlled'],
  });
  const page = await browser.newPage();

  const solver = new CaptchaSolver({
    page,
    apiKey: 'YOUR_CAPGURU_API_KEY',
    debug: true,
    attempts: 5,
  });
  await solver.setup();

  await page.goto('https://example.com/with-captcha');

  try {
    const kind = await solver.auto(30);
    console.log('Captcha:', kind || 'not found');
  } catch (e) {
    if (e instanceof CapGuruFatalError) console.log('API key or balance problem:', e.message);
    else console.log('Not solved:', e.message);
  } finally {
    await browser.close();
  }
})();

Почему солвер создаётся до перехода на страницу

При создании солвер начинает запоминать картинки капчи, которые загружает браузер, и переключает hCaptcha на английский язык. Если создать его после page.goto(), картинки первой загрузки будут пропущены, а hCaptcha может остаться на языке сайта.

Почему браузер запускается с такими параметрами

При запуске Puppeteer по умолчанию сайты видят, что браузером управляет программа (navigator.webdriver равно true), и Google и GeeTest показывают задания сложнее или не пропускают вовсе. Параметры из примера отключают этот признак.

Методы ​

Автоматически:

await solver.auto(30);      // найти капчу и решить, вернёт тип или null
await solver.detect();      // только определить тип, не решая
await solver.setup();       // подготовка, вызывать до page.goto()

auto() не решает Cloudflare Turnstile и reCAPTCHA v3: для них есть методы токенов ниже.

Решение на странице, для конкретного типа:

await solver.solveRecaptcha2();
await solver.solveHcaptcha();
await solver.solveOther();       
await solver.solveGeetest();
await solver.solveFuncaptcha();
await solver.solveTiktok();
await solver.solveAws();

Токены и текстовые капчи (с версии 0.5.0):

await solver.solveRecaptchaToken();     // reCAPTCHA v2 или v3, определяется по странице
await solver.solveRecaptchaToken({ version: 'v3', action: 'login', enterprise: true });
await solver.solveTurnstileToken();     // Cloudflare Turnstile
await solver.solveImageCaptcha('#captcha_img', { fillSelector: '#captcha_input' });
await solver.getBalance();              // баланс аккаунта
solver.cancel();                        // остановить текущее решение
  • solveRecaptchaToken() и solveTurnstileToken() сами находят на открытой странице sitekey, action и признак Enterprise и вставляют токен в страницу: reCAPTCHA v2 — в g-recaptcha-response и callback сайта, Turnstile — в cf-turnstile-response и data-callback. Возвращают { token, taskId }. Для v3 action по умолчанию verify.
  • solveImageCaptcha() отправляет ту картинку, что показана на странице (снимок элемента), и не скачивает её заново: многие сайты на каждый запрос выдают новую капчу. С fillSelector вводит ответ в поле. Возвращает { text, taskId }.

auto() и detect() возвращают тип капчи:

ЗначениеКапча
recaptcha2reCAPTCHA v2
hcaptchahCaptcha
yandexOther
geetestGeeTest v3 / v4
funcaptchaFunCaptcha (Arkose Labs)
tiktokTikTok
awsAWS WAF
nullКапча не найдена за отведённое время

Параметры auto():

ПараметрТипПо умолчаниюОписание
timeoutnumber30Сколько секунд ждать появления капчи. На медленных сайтах лучше 45–60
pollnumber0.5Как часто проверять страницу, в секундах

Без браузера ​

Токены и текстовые капчи можно получать и без Puppeteer, через клиент API:

javascript
const { CapGuruClient } = require('capguru');
const client = new CapGuruClient('ВАШ_КЛЮЧ');   // по умолчанию https://api2.cap.guru, при сбое — https://api.cap.guru

await client.getBalance();
await client.recaptchaV2Token({ sitekey, pageurl, invisible: false });
await client.recaptchaV3Token({ sitekey, pageurl, action: 'verify', enterprise: false });
await client.turnstileToken({ sitekey, pageurl });
await client.imageText(bufferИлиBase64, { vernet: 0 });   // vernet 22 — арифметика, результат вычисляется
await client.solveTask({ method: 'geetest', gt, challenge, pageurl });   // любая другая задача

Методы токенов возвращают { token, taskId }, imageText — { text, taskId } (и expression для арифметики). enterprise: true отправляет enterprise=1 (только для v3).

Поддерживаемые капчи ​

КапчаНа страницеТокен
reCAPTCHA v2 / невидимая v2ДаДа
reCAPTCHA v3 / v3 EnterpriseДа
Cloudflare TurnstileДа
hCaptchaДа
OtherДа
GeeTest v3 / v4Да
FunCaptchaДа
TikTokДа
AWS WAFДа
Текстовые капчиДа

Параметры конструктора ​

ПараметрТипПо умолчаниюОписание
pagePage—Экземпляр страницы Puppeteer
apiKeystring—API-ключ Cap.Guru
serverstring'https://api.cap.guru'Адрес сервера API. За пределами России используйте 'https://api2.cap.guru'
attemptsnumber5Максимальное число попыток. Для GeeTest и FunCaptcha лучше 8–10: они часто показывают несколько раундов картинок подряд
timeoutnumber300Сколько секунд даётся на решение капчи на странице. Можно задать и для отдельного вызова: solver.solveGeetest('', { timeout: 120 })
debugbooleanfalseВывод отладочных сообщений
selectorstring''CSS-селектор контейнера капчи, если на странице их несколько

Для токенов и текстовых капч время ожидания по умолчанию — 120 секунд, оно задаётся параметром timeout при вызове метода.

Требования ​

  • Puppeteer 24 или 25
  • Node.js 18 или новее (для Puppeteer 25 нужен Node.js 22.12 или новее)

Обработка ошибок ​

  • CapGuruFatalError — неверный API-ключ или нулевой баланс. Модуль сразу прекращает попытки.
  • CapGuruSolveError — капчу не удалось решить за все попытки или вышло время. Для токенов и текстовых капч в ошибке есть taskId.

Оба класса наследуются от Error:

javascript
const { CapGuruFatalError, CapGuruSolveError } = require('capguru');

try {
  const kind = await solver.auto(30);
  console.log('Captcha:', kind || 'not found');
} catch (e) {
  if (e instanceof CapGuruFatalError) {
    console.log('Проблема с API-ключом или балансом:', e.message);
  } else if (e instanceof CapGuruSolveError) {
    console.log('Капча не решена:', e.message);
  } else {
    throw e;
  }
}

Что значат коды ошибок API, описано на странице кодов ошибок.