Модуль Node.js для решения капчи в Puppeteer
Модуль capguru решает капчу прямо на странице, которой управляет ваш скрипт на Puppeteer: кликает по картинкам, перетаскивает ползунок и проходит другие задания, а тип капчи на странице умеет определять сам. Начиная с версии 0.5.0 он также получает токены reCAPTCHA и Cloudflare Turnstile, распознаёт текстовые капчи и работает без браузера.
Проверить скрипт можно на демо-страницах капч. Если вы пишете на Python, есть такой же модуль для Python для Playwright и Selenium.
Версии
| Версия модуля | Скачать | Изменения |
|---|---|---|
| 0.5.0 | npm · 0.5 | Токены reCAPTCHA v2/v3 (Enterprise) и Cloudflare Turnstile, текстовые капчи, клиент без браузера, таймауты и CapGuruSolveError и другое |
| 0.4 | 0.4 | Автоопределение капчи auto(), добавлен AWS WAF |
Установка
Модуль опубликован на npm:
npm install capguru puppeteerconst { CaptchaSolver, CapGuruFatalError, CapGuruSolveError } = require('capguru');Обновление до последней версии:
npm install capguru@latestУстановка без npm
Скачайте архив из таблицы версий, скопируйте папку capguru в свой проект и установите Puppeteer:
npm install puppeteerПодключайте модуль по относительному пути: require('./capguru').
Как использовать
- Импортируйте
CaptchaSolverиз пакета. - Запустите браузер, как в примере ниже, и создайте солвер до перехода на страницу с капчей, затем вызовите
await solver.setup(). - Откройте страницу и вызовите
await solver.auto(): модуль сам найдёт капчу и решит её.
Если тип капчи известен заранее, можно вызвать нужный метод напрямую.
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 }. Для v3actionпо умолчаниюverify.solveImageCaptcha()отправляет ту картинку, что показана на странице (снимок элемента), и не скачивает её заново: многие сайты на каждый запрос выдают новую капчу. СfillSelectorвводит ответ в поле. Возвращает{ text, taskId }.
auto() и detect() возвращают тип капчи:
| Значение | Капча |
|---|---|
recaptcha2 | reCAPTCHA v2 |
hcaptcha | hCaptcha |
yandex | Other |
geetest | GeeTest v3 / v4 |
funcaptcha | FunCaptcha (Arkose Labs) |
tiktok | TikTok |
aws | AWS WAF |
null | Капча не найдена за отведённое время |
Параметры auto():
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
timeout | number | 30 | Сколько секунд ждать появления капчи. На медленных сайтах лучше 45–60 |
poll | number | 0.5 | Как часто проверять страницу, в секундах |
Без браузера
Токены и текстовые капчи можно получать и без Puppeteer, через клиент API:
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 | Да | |
| Текстовые капчи | Да |
Параметры конструктора
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
page | Page | — | Экземпляр страницы Puppeteer |
apiKey | string | — | API-ключ Cap.Guru |
server | string | 'https://api.cap.guru' | Адрес сервера API. За пределами России используйте 'https://api2.cap.guru' |
attempts | number | 5 | Максимальное число попыток. Для GeeTest и FunCaptcha лучше 8–10: они часто показывают несколько раундов картинок подряд |
timeout | number | 300 | Сколько секунд даётся на решение капчи на странице. Можно задать и для отдельного вызова: solver.solveGeetest('', { timeout: 120 }) |
debug | boolean | false | Вывод отладочных сообщений |
selector | string | '' | CSS-селектор контейнера капчи, если на странице их несколько |
Для токенов и текстовых капч время ожидания по умолчанию — 120 секунд, оно задаётся параметром timeout при вызове метода.
Требования
- Puppeteer 24 или 25
- Node.js 18 или новее (для Puppeteer 25 нужен Node.js 22.12 или новее)
Обработка ошибок
CapGuruFatalError— неверный API-ключ или нулевой баланс. Модуль сразу прекращает попытки.CapGuruSolveError— капчу не удалось решить за все попытки или вышло время. Для токенов и текстовых капч в ошибке естьtaskId.
Оба класса наследуются от Error:
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, описано на странице кодов ошибок.