# @fisch0920/puppeteer-extra-plugin-recaptcha 中文文档 规范地址：https://npmcn.com/package/%40fisch0920/puppeteer-extra-plugin-recaptcha/ 版本：3\.6\.6 npm 元数据更新时间：2022-12-18T05:20:46.183Z 中文译文更新时间：2026-11-14T20:26:04.372Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fisch0920/puppeteer-extra-plugin-recaptcha 原文对照：https://npmcn.com/package/%40fisch0920/puppeteer-extra-plugin-recaptcha/?lang=original 项目主页：https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-recaptcha 源码仓库：https://github.com/berstend/puppeteer-extra ## 关键信息（来自 npm 元数据） - 包体积（解压后）：418 kB，36 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=9\.11\.2 - 运行依赖：3 个 - peer 依赖：playwright-extra \*，puppeteer-extra \* - 首次发布：2022-12-18T05:20:45.811Z - 最新版本发布：2022-12-18T05:20:46.036Z - 近 30 天下载量：4108（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：1（近 12 个月 0 个） ## 中文简介 自动解决 reCAPTCHA 和 hCaptchas 的傀儡外插件 . ## 安装 ```sh npm install @fisch0920/puppeteer-extra-plugin-recaptcha ``` 也可以使用：`pnpm add @fisch0920/puppeteer-extra-plugin-recaptcha`、`yarn add @fisch0920/puppeteer-extra-plugin-recaptcha`、`bun add @fisch0920/puppeteer-extra-plugin-recaptcha` ## README # 木偶- 外插件- 抓取 [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/berstend/puppeteer-extra/Test/master)](https://github.com/berstend/puppeteer-extra/actions) [![Discord](https://img.shields.io/discord/737009125862408274)](https://extra.community/) [![npm](https://img.shields.io/npm/dt/puppeteer-extra-plugin-recaptcha.svg)](https://www.npmjs.com/package/puppeteer-extra-plugin-recaptcha) [![npm](https://img.shields.io/npm/v/puppeteer-extra-plugin-recaptcha.svg)](https://www.npmjs.com/package/puppeteer-extra-plugin-recaptcha) > A 类 [木偶外传](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra) 财务报告和审定财务报表 [剧作家外出](https://github.com/berstend/puppeteer-extra/tree/master/packages/playwright-extra) 自动解决 reCAPTCHA 和 hCaptchas 的插件 . ![](https://i.imgur.com/SWrIQw0.gif) ## 安装 ```bash yarn add puppeteer-extra-plugin-recaptcha # - or - npm install puppeteer-extra-plugin-recaptcha ``` 如果这是你第一次 [木偶外传](https://github.com/berstend/puppeteer-extra) 插件这里的所有您需要的 : ```bash yarn add puppeteer puppeteer-extra puppeteer-extra-plugin-recaptcha # - or - npm install puppeteer puppeteer-extra puppeteer-extra-plugin-recaptcha ``` **更改日志** ##### 最新 > 🎁 **说明:** 直到我们把更改日志更新到 标记下的文件,请跟随 `#announcements` 我们的频道 [不和服务器](https://extra.community/) 用于更新和更改日志信息. _旧更改日志 :_ ##### `3.1.9` - 支持非表格形式的 " reCAPTCHA " ([57号](https://github.com/berstend/puppeteer-extra/issues/57)(中文(简体) ) - 使脚本检测更模糊( M)[48号](https://github.com/berstend/puppeteer-extra/issues/48)(中文(简体) ) ##### `3.1.6` - 现在,我们将在浏览器实例中的任何现有的页面和框架中加入我们的自定义方法. - 我们环境申报的固定参考导入路径. ##### `3.1.5` - 现在还支持在框架内解决重新谈判和谈判问题,如果需要的话: ```js for (const frame of page.mainFrame().childFrames()) { await frame.solveRecaptchas() } ``` ##### `3.1.4` - 改进了 TypeScript 的经验: 我找到了一种方法, 使您的 TypeScript 编译器自动意识到添加到 `Page` 财务报告和审定财务报表 `Frame` 对象(例如:. `page.solveRecaptchas()`) (中文(简体) ). - 如果提供者丢出错误, 我们现在打印一个警告( 如无效的 api 密钥) ## 使用量 该插件基本上提供了一个强大的 `page.solveRecaptchas()` 做一切需要自动的方法. ```js // puppeteer-extra is a drop-in replacement for puppeteer, // it augments the installed puppeteer with plugin functionality const puppeteer = require('puppeteer-extra') // add recaptcha plugin and provide it your 2captcha token (= their apiKey) // 2captcha is the builtin solution provider but others would work as well. // Please note: You need to add funds to your 2captcha account for this to work const RecaptchaPlugin = require('puppeteer-extra-plugin-recaptcha') puppeteer.use( RecaptchaPlugin({ provider: { id: '2captcha', token: 'XXXXXXX' // REPLACE THIS WITH YOUR OWN 2CAPTCHA API KEY ⚡ }, visualFeedback: true // colorize reCAPTCHAs (violet = detected, green = solved) }) ) // puppeteer usage as normal puppeteer.launch({ headless: true }).then(async browser => { const page = await browser.newPage() await page.goto('https://www.google.com/recaptcha/api2/demo') // That's it, a single line of code to solve reCAPTCHAs 🎉 await page.solveRecaptchas() await Promise.all([ page.waitForNavigation(), page.click(`#recaptcha-demo-submit`) ]) await page.screenshot({ path: 'response.png', fullPage: true }) await browser.close() }) ``` **类型脚本使用** ```ts // `puppeteer-extra` and the recaptcha plugin are written in TS, // hence you get perfect type support out of the box :) import puppeteer from 'puppeteer-extra' import RecaptchaPlugin from 'puppeteer-extra-plugin-recaptcha' puppeteer.use( RecaptchaPlugin({ provider: { id: '2captcha', token: 'ENTER_YOUR_2CAPTCHA_API_KEY_HERE' } }) ) // Puppeteer usage as normal (headless is "false" just for this demo) puppeteer.launch({ headless: false }).then(async browser => { const page = await browser.newPage() await page.goto('https://www.google.com/recaptcha/api2/demo') // Even this `Puppeteer.Page` extension is recognized and fully type safe 🎉 await page.solveRecaptchas() await Promise.all([ page.waitForNavigation(), page.click(`#recaptcha-demo-submit`) ]) await page.screenshot({ path: 'response.png', fullPage: true }) await browser.close() }) ``` 如果您想看到调试输出 只运行您的脚本这样: ```bash DEBUG=puppeteer-extra,puppeteer-extra-plugin:* node myscript.js ``` _**提示 :** 复选插件与该插件一起工作效果良好 [隐形插件](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth)。 。 。 ._ ## 动机 这几天 [盖茨](https://en.wikipedia.org/wiki/CAPTCHA) 不幸的是,到处都有 [重新来过](https://developers.google.com/recaptcha/) 拥有该空间最大的"市场份额"( > 80%). 情况变得非常糟糕, 隐私意识的用户(追踪屏蔽器、VPN)受到严厉惩罚. 以及有些人认为我们被迫从事免费劳动, 训练谷歌的各种机器学习活动. 无论如何,我强烈认为,目前形式的卡布查已经失败了。 他们对人类来说是一个比机器人更大的障碍和烦恼,这使得机器人变得无用. 我的无政府主义者对这次讨论的贡献是展示这种荒谬,用一个用于机器人的插件 **单行代码是绕过任何地点的 reCAPTCHA 所需要的**。 。 。 . > 注:自 `v3.3.0` 插件将解析 [h captchas (英语)](https://www.hcaptcha.com/) 他们通过他们的Cloudflare合伙关系获得了巨大的市场份额. ## 提供者 我考虑让插件直接解决 Captchas(例如使用 [音频挑战](https://github.com/dessant/buster) 和语音对文本的 API ),但外部解决方案提供者非常便宜和可靠,因此这样做真的没有好处. QQ(ツ) /' _请注意:_ 您需要为这个插件配置的提供者来完成魔法. 如果你决定使用内置的2captcha供应商,你需要在你的2captcha账户中添加资金. ### 2卡普查语name 根据我的经验,目前是唯一一个内建的解决方案提供者,因为它是最便宜和最可靠的. 如果你愿意 免费的Captcha的功劳... .. [在这里注册](https://2captcha.com/?from=6690177) (参考链接,允许我写自动测试 他们的API). - 费用:1,000 reCAPTCHA(和hCaptchas),3美元 - 延迟: 解决 reCAPTCHA 需要10至60秒 - 出错率( 不正确的解决方案) : 很少见 #### 其他供应商 通过提供插件而不是2captcha证书(在API Docs中解释),也可以轻松地使用自己的提供者. 新供应商的公关也值得欢迎. ## Q&A ### 怎么会这样? - 被传唤时 `page.solveRecaptchas()` 插件将尝试找到任何活跃的 reCAPTCHAS & hCaptchas,提取它们的配置,将它传递给指定的解决方案提供者,取出解决方案并放回页面(触发可能需要的任何回调). ### 制作好了吗? - 是的,该插件得到积极维护,经过几年的战斗加固,并被用于高工作量生产设置. ### 如何恢复CAPTCHA的功能? - 使用每个站点的再CAPTCHA `sitekey`. 有趣的是,解决一项挑战后的反应符号(目前)不与特定会话或IP挂钩,可以传给其他人(直到到期)。 外部解决方案提供者就是这样运作的: 他们得到一个 `sitekey` 和 URL , 解决挑战并用响应符响应. - 此插件以通用而有力的方式实现所有这些步骤的自动化( 侦测 Captchas, 提取其配置和 `sitekey`)以及触发网站所有者可能已经指定的(可选)回复. ### 普通的图像封面也支持吗 ? - 没有 此插件只关注 reCAPTCHAs 和 hCaptchas , 其好处是完全自动. QQ ### 那隐形的复方CAPTCHA呢? - [隐形回转](https://developers.google.com/recaptcha/docs/invisible) 被支持。 它们基本上用来计算一个分数 用户是多么可能是一个机器人。 基于这个分数,站点所有者可以阻止访问资源,或者(最经常的)向用户呈现reCAPTCHA的挑战(这个插件可以解决). 这个 [隐形插件](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth) 因为它掩盖了木偶兵的用途. - 从技术上讲,插件支持: reCAPTCHA v2, reCAPTCHA v3, 隐形 reCAPTCHA, hCaptcha, 隐形 hCaptcha. 所有这些(还有多种)都是在 `page.solveRecaptchas()` 名为. ### 我什么时候打电话 `page.solveRecaptchas()`? 吗? - reCAPTCHA 将自动解析 **可见** (单位:千美元)_他们的"我不是机器人"在DOM中_) (中文(简体) ). 如果需要,你有责任做任何必要的行动 触发显示的夹克. - 关于reCAPTCHA/hCaptchas"隐形"版本的说明: 它们没有显示一个可见的复选框 iframe, 插件会解决任何公开的挑战弹出 。 : - ) - 如果您在浏览到一页后立即调用插件, 它会自动等待 reCAPTCHA 脚本( 如果有的话) 已装入并初始化 . - 如果你打电话 `page.solveRecaptchas()` 在一个没有reCAPTCHAs的页面上,不会发生什么坏事(QQ),但承诺会解决,你的其余代码会正常执行. - 在解析 reCAPTCHA后,插件将自动检测并触发它们 [可选回调](https://developers.google.com/recaptcha/docs/display#render_param). 这可能导致提交表格和进行页面导航,这取决于网站所有人如何实施reCAPTCHA. ## 调试 ```bash DEBUG=puppeteer-extra,puppeteer-extra-plugin:* node myscript.js ``` ## 精细的谷物控制 ### 默认 默认情况下, 插件永远不会丢出, 但默默返回任何错误 `{ error }` 结果对象的属性。 你可以通过传递改变行为 `throwOnError: true` 改为初始化并使用 `try/catch` 块来捕捉错误. 为方便起见并因其看起来酷,插件会根据其状态(紫色=被检测并被解出,绿色=被解出)而将 reCAPTCHA"颜色化". 你可以通过路过关闭这个功能 `visualFeedback: false` 到插件初始化器. ### 选项 ```ts interface PluginOptions { /** Visualize reCAPTCHAs based on their state */ visualFeedback: boolean // default: true /** Throw on errors instead of returning them in the error property */ throwOnError: boolean // default: false /** Only solve captchas and challenges visible in the browser viewport */ solveInViewportOnly: boolean // default: false /** Solve scored based captchas with no challenge (e.g. reCAPTCHA v3) */ solveScoreBased: boolean // default: false /** Solve invisible captchas that have no active challenge */ solveInactiveChallenges: boolean // default: false } ``` ### 结果对象 ```js const { captchas, filtered, solutions, solved, error } = await page.solveRecaptchas() ``` - `captchas` 是在页面中找到的一列相机 - `filtered` 是一个已检测到但因插件选项被忽略的 captcha 阵列 - `solutions` 是从提供者返回的一系列解决方案 - `solved` 是页面上“ solved (= solution entered) ” 的数组 ### 手动控制流程 `page.solveRecaptchas()` 是一种将下列步骤包起来的便利方法: ```js let { captchas, filtered, error } = await page.findRecaptchas() let { solutions, error } = await page.getRecaptchaSolutions(captchas) let { solved, error } = await page.enterRecaptchaSolutions(solutions) ``` ### 代理 如果您希望在解决 Captcha 时使用特定代理( = IP 地址) , 您可以设置 enviroment 变量 `2CAPTCHA_PROXY_TYPE` 财务报告和审定财务报表 `2CAPTCHA_PROXY_ADDRESS`。 。 。 . ## 解决问题 ### 解决 Iframes 中的夹克 默认情况下,插件只会解决reCAPTCHA在即时页面上出现的问题. 在框中遇到 Captchas 时,插件会扩展 `Puppeteer.Frame` 具有自定义方法的对象: ```js // Loop over all potential frames on that page for (const frame of page.mainFrame().childFrames()) { // Attempt to solve any potential captchas in those frames await frame.solveRecaptchas() } ``` 此外,您可能想要禁用站点隔离,所以傀儡可以访问 [跨原生地框架](https://github.com/puppeteer/puppeteer/issues/2548)数字 : ```js puppeteer.launch({ args: [ '--disable-features=IsolateOrigins,site-per-process,SitePerProcess', '--flag-switches-begin --disable-site-isolation-trials --flag-switches-end' ] }) ``` ### 在已有浏览器页面中解决 captchas 如果你没有用 `browser.newPage()` 但是重新使用现有的 `about:blank` 选项卡(由于各种原因不推荐) `page.solveRecaptchas is not a function` 错误, 因为插件尚未连接到此页面 。 作为工作,您可以手动将已有的页面添加到插件的生命周期方法中 : ```js const recaptcha = RecaptchaPlugin() const pages = await browser.pages() for (const page in pages) { // Add plugin methods to existing pages await recaptcha.onPageCreated(page) } ``` ### 提示 - 如果某事不起作用或报告问题, 请使用调试日志 . - 检查过滤阵列中被忽略的cabtchas, 以防您打算解决的cabtcha被忽略, 被过滤的cabtchas将声明它们被忽略的原因( 或者更好: 由哪个插件选项负责) - 记住,默认情况下,插件只会解决"活性"captchas(指可见的复选框或活性挑战弹出). 在极端情况下(像一个非常奇怪或超慢的加载站点),您可以帮助插件,确保您想要解决的 Captcha 在呼叫前就在那里 `page.solveRecaptchas`数字 : ```js await page.waitForSelector('iframe[src*="recaptcha/"]') await page.solveRecaptchas() ``` * * * ## 许可证 版权: 2018-2022, [贝斯特恩德](https://github.com/berstend)根据麻省理工学院的许可证释放. ## 常见问题 ### @fisch0920/puppeteer-extra-plugin-recaptcha 是什么？ 自动解决 reCAPTCHA 和 hCaptchas 的傀儡外插件 \. ### 如何安装 @fisch0920/puppeteer-extra-plugin-recaptcha？ 在项目目录运行 npm install @fisch0920/puppeteer-extra-plugin-recaptcha，或使用 pnpm add / yarn add / bun add。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=9\.11\.2。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 可以商用吗？ @fisch0920/puppeteer-extra-plugin-recaptcha 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 的下载量有多少？ 根据 npm 官方下载统计，@fisch0920/puppeteer-extra-plugin-recaptcha 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,108 次，日均约 137 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fisch0920/puppeteer-extra-plugin-recaptcha 还在维护吗？ 最新版本 3\.6\.6 发布于 2022/12/18（3 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/12/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。