puppeteer-cluster CAPTCHA: Görev Başına Bir Token ile Çözün

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

Bir puppeteer-cluster captcha çözmek için çözücüyü görev fonksiyonunun içinde çağırın ve token’ı yerel bir sabitte tutun. Bir reCAPTCHA token’ı bir kez işe yarar; bu yüzden görevler arasında paylaşılan tek bir token yalnızca tek bir formu geçirebilir. Bu kılavuz, sabit bir lisansla kendi Windows bilgisayarınızdaki CapSkip uygulamasıyla konuşan capskip Node.js paketiyle o script’i kurar, sonra üç limit ayarlar: maxConcurrency, cluster zaman aşımı ve retryLimit. Tek sayfalık sürüm şu sayfada: Puppeteer CAPTCHA çözücü sayfası.

Neye ihtiyacınız var

  • Bir Windows bilgisayarında çalışan CapSkip, host ve portla erişilir (varsayılan 127.0.0.1 ve 8080). Server modu onun ağ veya genel IP’nizi dinlemesini sağlar; böylece başka bir bilgisayardaki bir cluster aynı çözücüyü kullanabilir. İkisi arasında geçişi bağlantı ayarları sağlar.
  • Puppeteer 25.17.0 için Node.js 22.12 veya üzeri (engines alanı), Puppeteer 24.43.1 için Node.js 18 veya üzeri. İlkiyle Node 24.22.0 ve 25.2.1, ikincisiyle Node 20.11.1 ve 24.22.0 çalıştırdım; Node 18 ya da 22 değil.
  • puppeteer-cluster 0.25.0 (engines alanı yok, peer aralığı Puppeteer 24.0.0 veya daha yenisi) ve capskip 1.7.0 (Node 18 veya üzeri), çalıştırdığım sürümler.
  • Otomatikleştirmenize izin verilen, reCAPTCHA v2 onay kutusu gösteren bir sayfa.

Kütüphanenin ne kadar yakın zamanda yayımlandığını kontrol edin. Kasım 2026’da baktığımda en son sürüm 0.25.0 (13 Kasım 2025) idi, master’da daha yeni bir commit yoktu ve 112 issue ile 16 pull request açıktı. Arşivlenmiş değil; o hızın size uyup uymadığını puppeteer-cluster README dosyasından görebilirsiniz.

puppeteer-cluster captcha script’i nasıl test edildi: gerçek CapSkip uygulamasına ya da gerçek bir reCAPTCHA sayfasına karşı değil. Her çalıştırma, yazdığım bir in.php ve res.php mock’unu, bir g-recaptcha div’i, bir data-sitekey özniteliği ve g-recaptcha-response adlı gizli bir textarea içeren bir yedek form sitesini kullandı. Bu, Google’ın widget’ı değildir. Kurallar benimdir: token başına tek kullanım, bir token sayfasının sitekey’ine uymalı ve form CSRF cookie’sini ister. Mock ayrıca, CapSkip uygulama kaynağında okuduğum biçim kuralına uymayan bir sitekey’i de reddeder. Çalıştırmaların çoğu Chrome for Testing 156.0.8078.47’yi PUPPETEER_EXECUTABLE_PATH üzerinden kullandı ve yazıldığı gibi kurulum bloğu, npm’in indirdiği Chrome ile de çalıştı (Puppeteer 25.17.0 için 157.0.8103.50, 24.43.1 için 148.0.7778.97). npm 11, [email protected]’ın henüz allowScripts kapsamında olmayan bir kurulum script’i olduğu konusunda uyarır, ama indirme yine de gerçekleşti. Kurulum script’leri kapalıyken script şu hatayla durur: Could not find Chrome.

Script’i kurun

1. Adım: projeyi ve ayarları oluşturun

Önce package.json oluşturun: Windows’ta npm 11.19.1 ile, onsuz bir klasör paketlerini üst klasöre kurdu.

# 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 ile 22.11 arasında, yukarıdaki satır yerine npm install puppeteer@24 puppeteer-cluster capskip kullanın. Node 20.11.1 üzerinde yukarıdaki satır, EBADENGINE uyarılarıyla Puppeteer 25.17.0 kurdu ve script şu hatayla öldü: ERR_REQUIRE_ESM.

Sonra cluster-solve.js adlı bir dosya başlatın. Bu blok ve 2. ile 4. Adım’daki bloklar sırayla ona girer ve sonuncusu gelene kadar hiçbir şey çalışmaz. SDK CAPSKIP değişkenlerinden hiçbirini kendiliğinden okumaz; bu yüzden script host ve portu onlardan kendisi okur.

// 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. Adım: görevin içinde çözün

Her görev sayfasını yükler, sitekey’i okur, CapSkip’ten o sayfanın adresi için bir token ister, onu gizli textarea’ya yazar ve gönder düğmesine basar. Gerçek bir sayfada o textarea, Google’dan gelen script widget’ı çizdikten sonra belirir, ki çözüm süresi bunu normalde kapsar; ben yalnızca statik olanı test ettim. Siteniz bir data-callback bildiriyorsa token’ı yazdıktan sonra onu çağırın; benim yedeğimde yok, bu yüzden bunu test etmedim. 200 durum kontrolü yalnızca yedek siteye uyar; gerçek siteler formu çoğunlukla 200 ile bir hatayla yeniden gösterir. Node.js’te reCAPTCHA v2 rehberi tek sayfalık akışı kapsar.

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. Adım: yalnızca yeniden denemenin düzeltebileceğini yeniden deneyin

retryLimit bir görevin fırlattığı her hatayı yeniden dener; bu yüzden bu sarmalayıcı önce hata türüne bakar. ERROR_CAPTCHA_UNSOLVABLE diyen bir ApiException, CapSkip’in o görevi çözemediği anlamına gelir ve yenisi işe yarayabilir. Diğer her ApiException ve her ValidationException isteğinizden ya da limitlerinizden gelir; bu yüzden sarmalayıcı onları kaydeder ve görevi bitirir. Varsayılan ayarlarla CapSkip eksik ya da bozuk bir sitekey’i hemen reddeder (API belgelerinde ERROR_GOOGLEKEY), bu da sarmalayıcıda biter; geçersiz veriye sahip görevleri listeleyen ayar varsayılan olarak kapalıdır. Sarmalayıcı yuva yok reddini yeniden denemez, çünkü cluster aynı dolu kuyruğa hemen yeniden denerdi: bunun yerine maxConcurrency değerini düşürün. Okuduğum uygulama kaynağında, sayfa için yanlış olan ama biçimi doğru bir anahtar çözülemez olarak yanıtlanır; bu yüzden retryLimit bitene kadar yeniden denenir.

// 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. Adım: cluster’ı başlatın ve sayfaları kuyruğa alın

Chrome varsayılan olarak headless başlar; başlatılan tarayıcının komut satırında bunu gördüm.

(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

Mock’a karşı sekiz form, üç sayfa ve 2 saniyelik bir mock çözümü, 8 formun hepsinin kabul edilmesini ve aynı anda en fazla 3 çözümü verdi. Bir çözüm gönderimden token’a 2 değil, 3,8 saniye sürdü; çünkü SDK 0; 0,25; 0,75; 1,75 ve 3,75 saniyede yoklar. Diğer çalışma zamanı kurulumları aynı çıktı, günlüğe hiçbir uyarı yazılmadı.

puppeteer-cluster captcha token’ı neden görevin içinde kalır

Cazip kısayol, görev fonksiyonunun üstünde tek bir değişkendir; script bu biçimi dışarıda bırakır.

// 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);
}

Mock’ta altı form 3 çözüm, 3 kabul edilen form ve 6 ret verdi, yeniden denemeler dahil. İlk üç görev boş bir değişken görür ve geçer. Sonraki her görev en son saklanan token’ı yeniden kullanır; o ya başka bir sitekey’e aittir ya da zaten kullanılmıştır. Yazıldığı hâliyle script, 8 form için 8 çözüm yaptı ve hiç ret olmadı.

Öteki tuzak cookie jar’dır. Varsayılan mod CONCURRENCY_CONTEXT her göreve özel bir tarayıcı bağlamı verir, CONCURRENCY_PAGE ise tek bir tane paylaştırır. Yedek sitem her sayfa yüklemesinde yeni bir CSRF cookie’si ayarlar; bu yüzden daha önce yüklenen görevler başarısız olur. Sekiz form, 10 çalıştırmada 12 ile 14 çözüm, 5 ile 8 CSRF reddi ve 6 ya da 7 kabul edilen form aldı. Kararlı bir cookie’si olan bir site bozulmazdı.

Birbiriyle uyuşması gereken üç limit

Bir puppeteer-cluster captcha script’inde puppeteer-cluster’ın maxConcurrency seçeneği, uçuştaki çözümleri sınırlar, çünkü her görev bir tane yapar ve 0 sınır yok demektir. CapSkip’in kendi üst sınırı vardır: Settings içindeki reCAPTCHA satırındaki, varsayılanı 10 olan "Max. Threads" ayarı. Fazla görevler onun kuyruğunda en fazla "Wait Timeout" (varsayılan 250 saniye) kadar bekler ve SDK zaman aşımı bu beklemeyi içerir. İki çözüm yuvalı ve dört sayfalı mock’ta, 4 saniyelik bir çözüm gönderimden token’a beklemesiz 7,8 saniye, bir yuva için bekleyerek 12,8 saniye sürdü; çünkü SDK çözüm bittikten sonraki ilk kontrolde token’ı alır ve yaklaşık 3,8, 7,8 ve 12,8 saniyede kontrol eder. Kuyruk ayrıca kısadır. Değişiklik günlüğü, CapSkip 2.4.0’dan beri dolu bir kuyruğa gelen bir reCAPTCHA görevinin yuva yok hatasıyla reddedildiğini söyler ve okuduğum uygulama kaynağında kuyruk "Max. Threads" kadar derindir. Mock’um bu kuralı uygular: iki çözüm yuvası, iki görev kapasiteli bir kuyruk ve aynı anda sekiz sayfayla 4 form kabul edildi ve 4’ü ERROR_NO_SLOT_AVAILABLE ile pes etti; dört sayfa ise 8 formun hepsi için yetti. maxConcurrency değerini "Max. Threads" değerinde ya da altında tutun ve tek bir CapSkip üzerindeki iki cluster’ın onu paylaştığını unutmayın. Uçuştaki her çözüm ayrıca bir IP adresi kullanır ve kurulum kılavuzu CapSkip’e en az "Max. Threads" kadar proxy vermenizi söyler.

puppeteer-cluster zaman aşımı, SDK beklemesini ve sayfa işini aşmalıdır. cluster varsayılanı 30 saniyedir ve SDK, reCAPTCHA için 300 saniye bekler, siz recaptchaTimeout ayarlamadıkça. timeout seçeneği kaldırılıp 40 saniyelik bir mock çözümü kullanıldığında, Timeout hit: 30000 script başladıktan yaklaşık 31 saniye sonra göründü, ama süreç yaklaşık 44’te çıktı, çünkü terk edilen görev yoklamaya devam etti. 3 saniyelik bir SDK limiti 3,8 saniyede tetiklendi, çünkü SDK son tarihine yalnızca yoklamalar arasında bakar.

Bir zaman aşımı çözümü durdurmaz. Mock’ta, 12 saniyelik bir çözüm, dört form, iki sayfa ve bir yeniden deneme ile, 5 saniyelik bir cluster zaman aşımı 4 form için 8 çözüm, 2 sayfaya karşı en fazla 6 uçuşta çözüm ve zaten başarısız olmuş görevlere teslim edilen 8 token verdi. 3 saniyelik bir SDK beklemesi ve 9 saniyelik cluster zaman aşımı şu hatayı verdi: timeout 3 exceeded ve yine 8 çözüm. Gerçek bir CapSkip’in kimsenin yoklamadığı bir çözümü bırakıp bırakmadığı burada ölçülmedi. Kurulum kılavuzu, "Row Timeout" süresini (reCAPTCHA için 250 saniye) aşan bir çözümün durdurulduğunu söyler ve okuduğum uygulama kaynağında yoklama durduğunda bir işi iptal eden hiçbir kod bulmadım (okundu, çalıştırılmadı).

Hatalar, retryLimit ve sessiz başarısızlıklar

puppeteer-cluster’ın retryLimit ek denemeleri sayar: 1 iki deneme, 2 üç deneme demektir. Mock’un bir kez çözülemez diye reddettiği bir sayfa yeniden denemede kabul edildi ve retryLimit değeri 0 iken başarısız oldu ve çıkış kodu 1 idi.

3. Adım olmadan, yeniden denemelerin düzeltemeyeceği hatalar yine de yeniden denenir. retryLimit değeri 2 iken bozuk bir sitekey üç deneme aldı, SDK’nın ValidationException olarak bildirdiği desteklenmeyen bir seçenek de öyle. Sarmalayıcı ile her biri bir deneme aldı. Biçimi doğru ama mock’un her zaman çözülemez bildirdiği bir anahtar yine de üçünü de aldı.

cluster.execute() yeniden deneme kurallarını atlar; bunları retryLimit belirler: bir kez çözülemez olan sayfada retryLimit değeri 2 iken bir denemeden sonra reddetti, cluster.queue() ise yeniden denedi. Kuyruğa alınmış başarısız bir görev ayrıca sessizdir: taskerror dinleyicisi ve DEBUG değişkeni olmadan başarısız bir çalıştırma yalnızca özeti yazdırdı. DEBUG=puppeteer-cluster:log ayarı her başarısızlık için bir satır yazdırdı.

GördüğünüzNedenDüzeltme
Timeout hit: 30000CapSkip hâlâ çözerken cluster varsayılanı görevi bitirdicluster zaman aşımını SDK beklemesinin üstüne ayarlayın
timeout 90 exceededSDK bir token için beklemeyi bıraktıÇözümleri bilgisayarınızda ölçün, sonra iki zaman aşımını da yükseltin
ERROR_GOOGLEKEYSitekey eksik ya da bir reCAPTCHA anahtarı biçiminde değilSitekey’i okuyan seçiciyi kontrol edin; yeniden denemeyin
ERROR_NO_SLOT_AVAILABLECapSkip’e kuyruğunun alabileceğinden fazla görev ulaştıAyarla maxConcurrency değerini "Max. Threads" değerine eşit ya da altına
ERROR_PAGEURLSayfa adresi eksik ya da bir http veya https adresi değilYüklenen sayfanın adresini geçirin; yeniden denemeyin
connect ECONNREFUSED 127.0.0.1:12999O portta hiçbir şey dinlemiyorCapSkip’i başlatın ve host ile portu kontrol edin
Site gönderimlerin çoğunu reddediyor (benim yedeğim 403 yanıtı verir; sizinki hata sayfasıyla 200 verebilir)Paylaşılan bir token ya da paylaşılan bir cookie jarToken’ı yerel tutun; varsayılan modu kullanın

CapSkip’i bir sunucuda kullanma

Bir puppeteer-cluster captcha script’i yalnızca bir host ve bir port ister. Local modu 127.0.0.1’i dinler, bu yüzden cluster o bilgisayarda çalışmalıdır. Server modu ağ veya genel IP’nizi dinler ve CAPSKIP_HOST değerini o Windows bilgisayarına ayarlarsınız. Yalnızca 127.0.0.1’i test ettim. Server modu, CapSkip’in portuna her adresten izin vermesiyle başlar ve kendi izin kuralınız bunu daraltmaz; bu yüzden dışarıda kalması gereken adresler için bir Windows Firewall engelleme kuralı ekleyin.

FAQ

puppeteer-cluster güncel Puppeteer ile çalışır mı?

Script, Puppeteer 25.17.0 ve 24.43.1 üzerinde çalıştı. Bir havuzu kendiniz yönetmek istemiyorsanız, Crawlee rehberi kendi eşzamanlılığı ve yeniden denemeleri olan bir crawler’ı ele alır.

Önce her sayfayı çözüp cluster’ı sonra çalıştırabilir miyim?

Güvenli değil. reCAPTCHA doğrulama belgeleri bir token’ın iki dakika yaşadığını ve bir kez işe yaradığını söyler; bu yüzden görevi boş bir sayfaya ulaşmadan önce üretilen bir token bayatlamış olabilir. Script’in yaptığı gibi token’ı görevin içinde isteyin.

Kısa özet

Bir puppeteer-cluster captcha script’i şuna iner: görev başına bir çözüm, yerel bir sabitte tutulan bir token ve uyuşan limitler: maxConcurrency değerinin CapSkip’in aynı anda çözdüğünün altında ya da eşit olması, SDK beklemesinden uzun bir cluster zaman aşımı ve yalnızca bir yeniden denemenin düzeltebileceği hatalar için yeniden denemeler. CapSkip, sabit bir lisansla çalışan yerel bir captcha çözücü olduğu için bir yeniden deneme kendi bilgisayarınızda zamana mal olur, çözüm başına ücrete değil. Aynı paket yalnızca reCAPTCHA’yı değil, daha fazlasını çözer; hangi türleri çözdüğünü görmek için Node.js CAPTCHA çözücü sayfasına bakın.