puppeteer-cluster 验证码:每个任务一个 token

要识别 puppeteer-cluster 里的验证码,就在任务函数里调用识别工具,并把 token 放在一个局部常量里。reCAPTCHA 的 token 只能用一次,所以在任务之间共用一个 token,只能通过一个表单。本文用 capskip Node.js 包搭建这个脚本,它在统一授权定价下与你自己 Windows PC 上的 CapSkip 应用通信,然后设置三个限制: maxConcurrency、集群超时和 retryLimit。单页版本见 Puppeteer 验证码识别页面.
你需要什么
- 在 Windows PC 上运行的 CapSkip,通过主机和端口访问(默认是 127.0.0.1 和 8080)。Server mode 让它监听你的网络地址或公网 IP,所以另一台 PC 上的集群也能使用同一个识别工具。 连接设置 可以在这两种模式之间切换。
- Puppeteer 25.17.0 需要 Node.js 22.12 或更高版本(它的 engines 字段),Puppeteer 24.43.1 需要 Node.js 18 或更高版本。我用 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 年 11 月查看时,0.25.0(2025 年 11 月 13 日)是最新版本,master 上没有更新的提交,还有 112 个 issue 和 16 个 pull request 未关闭。它没有被归档,而 puppeteer-cluster README 能让你判断这个节奏是否适合你。
puppeteer-cluster captcha 脚本是这样测试的:没有对真实的 CapSkip 应用或真实的 reCAPTCHA 页面。每次运行都用了我写的 in.php 和 res.php 模拟服务器,外加一个带有 g-recaptcha div、data-sitekey 属性和名为 g-recaptcha-response 的隐藏 textarea 的替身表单站点。它不是 Google 的小组件。规则是我定的:每个 token 只能用一次,token 必须与所在页面的 sitekey 匹配,表单需要它的 CSRF cookie。模拟服务器还会拒绝不符合我在 CapSkip 应用源码里读到的形状规则的 sitekey。大多数运行通过 PUPPETEER_EXECUTABLE_PATH 使用 Chrome for Testing 156.0.8078.47,按原样写的安装代码块用 npm 下载的 Chrome 也能工作(Puppeteer 25.17.0 是 157.0.8103.50,24.43.1 是 148.0.7778.97)。npm 11 会警告 [email protected] 有一个尚未被 allowScripts 覆盖的安装脚本,但下载仍然发生了。关闭安装脚本后,脚本会停在 Could not find Chrome.
搭建脚本
第 1 步:创建项目和设置
先创建 package.json:在 Windows 上用 npm 11.19.1 时,没有它的文件夹会把包装到上一级文件夹里。
# 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 请求针对那个页面地址的 token,把它写进隐藏的 textarea,然后点击提交。在真实页面上,这个 textarea 在 Google 的脚本渲染出小组件之后才会出现,识别所花的时间通常已经涵盖了这一点;我只测试了静态的页面。如果你的站点声明了 data-callback,请在写入 token 之后调用它;我的替身页面没有,所以我没有测试这一点。状态码 200 的检查只适用于替身页面;真实站点常常会在 200 状态下再次显示带错误的表单。 Node.js 中的 reCAPTCHA v2 指南 讲的是单页流程。
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 会重试任务抛出的每一个错误,所以这个包装器先检查错误类型。一个写着 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException 表示 CapSkip 没能识别这个任务,新开一个任务可能会成功。其他任何 ApiException 和任何 ValidationException 都来自你的请求或你的限制,所以包装器记录它们并结束任务。在默认设置下,CapSkip 会立即拒绝缺失或格式错误的 sitekey(API 文档里的 ERROR_GOOGLEKEY),它最终结束在包装器里;列出数据无效任务的那个设置默认是关闭的。包装器不会重试没有空位的拒绝,因为集群会立刻重试进同一个已满的队列:请改为降低 maxConcurrency 。在我读到的应用源码里,格式正确但与页面不匹配的 key 会被答复为无法识别,所以它会一直重试,直到 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 默认以无头方式启动,我在被启动浏览器的命令行上看到了这一点。
(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 个识别在进行。一次识别从提交到拿到 token 用了 3.8 秒,不是 2 秒,因为 SDK 在 0、0.25、0.75、1.75 和 3.75 秒时轮询。其他运行环境的设置结果一致,没有记录任何警告。
为什么 puppeteer-cluster 验证码的 token 要留在任务里面
诱人的捷径是在任务函数上面放一个变量,脚本里没有采用这种写法。
// 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 次拒绝(包括重试)。前三个任务看到的是一个空变量,所以通过。之后的每个任务都复用最后存进去的那个 token,它要么属于另一个 sitekey,要么已经用过。按原样写的脚本为 8 个表单做了 8 次识别,没有任何拒绝。
另一个陷阱是 cookie jar。默认模式 CONCURRENCY_CONTEXT 给每个任务一个私有的浏览器上下文,而 CONCURRENCY_PAGE 共用一个。我的替身站点在每次页面加载时都设置一个新的 CSRF cookie,所以更早加载的任务会失败。八个表单在 10 次运行里用了 12 到 14 次识别,5 到 8 次 CSRF 拒绝,6 或 7 个表单被接受。一个 cookie 稳定的站点不会出这个问题。
必须一致的三个限制
在 puppeteer-cluster 验证码脚本里,puppeteer-cluster 的 maxConcurrency 选项限制同时进行的识别数,因为每个任务做一次识别,0 表示不限制。CapSkip 有它自己的上限:Settings 里 reCAPTCHA 那一行的 "Max. Threads" 设置,默认是 10。多出来的任务在它的队列里最多等 "Wait Timeout"(默认 250 秒),而 SDK 的超时包括这段等待。在模拟服务器里,有两个识别槽位和四个页面时,一次 4 秒的识别在不等待时从提交到拿到 token 用了 7.8 秒,在等槽位时用了 12.8 秒,因为 SDK 在识别结束之后的第一次检查时才取走 token,而它检查的时间大约是 3.8、7.8 和 12.8 秒。队列也很短。更新日志说,从 CapSkip 2.4.0 起,到达已满队列的 reCAPTCHA 任务会被以没有空位的错误拒绝,而在我读到的应用源码里,队列深度和 "Max. Threads" 一样。我的模拟服务器采用这条规则:在两个识别槽位、队列深度为二、八个页面同时到达时,4 个表单被接受,4 个以放弃告终,错误是 ERROR_NO_SLOT_AVAILABLE,而四个页面足以让 8 个全部成功。请把 maxConcurrency 保持在 "Max. Threads" 以下或与它相等,并记住同一个 CapSkip 上的两个集群共用它。每个进行中的识别还会占用一个 IP 地址,设置指南说要给 CapSkip 至少和 "Max. Threads" 一样多的代理。
puppeteer-cluster 的超时必须大于 SDK 的等待时间加上页面工作的时间。集群默认是 30 秒,而 SDK 对 reCAPTCHA 会等 300 秒,除非你设置 recaptchaTimeout。去掉 timeout 选项并使用 40 秒的模拟识别时, Timeout hit: 30000 在脚本启动约 31 秒后出现,但进程在约 44 秒才退出,因为被放弃的任务还在继续轮询。一个 3 秒的 SDK 限制在 3.8 秒时触发,因为 SDK 只在两次轮询之间查看它的截止时间。
超时并不会停止识别。在模拟服务器里,一次 12 秒的识别、四个表单、两个页面和一次重试,5 秒的集群超时产生了针对 4 个表单的 8 次识别,最多 6 个同时进行而页面只有 2 个,还有 8 个 token 被交给了已经失败的任务。3 秒的 SDK 等待加 9 秒的集群超时给出了 timeout 3 exceeded ,识别次数仍然是 8。真实的 CapSkip 是否会丢弃一个没人轮询的识别,这里没有测量。设置指南说,超过 "Row Timeout"(reCAPTCHA 为 250 秒)的识别会被停止,而在我读到的应用源码里,我没有找到轮询停止时取消作业的代码(只读过,没有运行)。
错误、 retryLimit 与静默失败
puppeteer-cluster 的 retryLimit 统计额外的尝试次数:1 表示两次尝试,2 表示三次。一个被模拟服务器拒绝一次、判为无法识别的页面,在重试时被接受了,而当 retryLimit 为 0 时,它失败了,退出码为 1。
没有第 3 步的话,重试解决不了的错误也会被重试。当 retryLimit 为 2 时,格式错误的 sitekey 用了三次尝试,不受支持的选项(SDK 把它报告为 ValidationException)也是如此。有了这个包装器,每个只用了一次。一个格式正确、模拟服务器始终报告为无法识别的 key 仍然用满了三次。
cluster.execute() 会跳过 retryLimit 所设的重试规则:在只会无法识别一次的页面上,当 retryLimit 为 2 时,它在一次尝试之后就被拒绝了,而 cluster.queue() 重试了。一个失败的排队任务也是静默的:没有 taskerror 监听器,也没有 DEBUG 变量时,一次失败的运行只打印汇总。设置 DEBUG=puppeteer-cluster:log 后,每次失败会打印一行。
| 你所看到的 | 原因 | 修复 |
|---|---|---|
Timeout hit: 30000 | 集群默认值在 CapSkip 仍在识别时就结束了任务 | 把集群超时设在 SDK 等待时间之上 |
timeout 90 exceeded | SDK 不再等待 token | 在你的 PC 上测量识别时间,然后把两个超时都调高 |
ERROR_GOOGLEKEY | sitekey 缺失,或者形状不像 reCAPTCHA 的 key | 检查读取 sitekey 的选择器;不要重试 |
ERROR_NO_SLOT_AVAILABLE | 到达 CapSkip 的任务比它的队列容得下的多 | 设置 maxConcurrency 不超过 "Max. Threads" |
ERROR_PAGEURL | 页面地址缺失,或者不是 http 或 https 地址 | 传入已加载页面的地址;不要重试 |
connect ECONNREFUSED 127.0.0.1:12999 | 那个端口上没有程序在监听 | 启动 CapSkip,并检查主机和端口 |
| 站点拒绝大多数提交(我的替身站点回复 403;你的站点可能回复带错误页面的 200) | 共用的 token 或共用的 cookie jar | 把 token 保持为局部变量;使用默认模式 |
在服务器上使用 CapSkip
puppeteer-cluster 验证码脚本只需要一个主机和一个端口。Local mode 监听在 127.0.0.1 上,所以集群必须运行在那台 PC 上。Server mode 监听你的网络地址或公网 IP,你把 CAPSKIP_HOST 设为那台 Windows PC。我只测试了 127.0.0.1。Server mode 启动时 CapSkip 会允许任何地址访问它的端口,你自己添加的允许规则并不能收窄这一点,所以请为应当被挡在外面的地址添加 Windows Firewall 阻止规则。
常见问题
puppeteer-cluster 能配合当前的 Puppeteer 使用吗?
这个脚本在 Puppeteer 25.17.0 和 24.43.1 上运行过。如果你不想自己管理一个池, Crawlee 指南 介绍了自带并发和重试的爬虫。
能不能先识别所有页面,之后再运行集群?
不安全。 reCAPTCHA 验证文档 说,一个 token 存活两分钟且只能用一次,所以在任务拿到空闲页面之前生成的 token 可能已经过期。请在任务里面请求,就像脚本做的那样。
简短版结论
puppeteer-cluster 验证码脚本归结起来就是:每个任务一次识别,token 放在局部常量里,以及彼此一致的限制: maxConcurrency 不超过 CapSkip 同时能识别的数量,集群超时长于 SDK 的等待,只对重试能解决的错误重试。CapSkip 是一款本地 验证码识别工具 ,采用统一授权定价,所以重试只花你自己 PC 上的时间,不产生按次识别的费用。同一个包识别的类型不止 reCAPTCHA, Node.js 验证码识别页面 列出了有哪些类型。
