
用于 puppeteer 和 playwright 的补丁集合,可避免自动化检测和信息泄露。有助于绕过 Cloudflare 和 DataDome 的 CAPTCHA 页面。易于打补丁/取消补丁,可按需启用/禁用。
本仓库包含用于增强流行 Web 自动化库的补丁。具体而言,它针对 puppeteer 和 playwright 包。
自动化库或浏览器行为的某些方面无法通过设置或命令行开关进行调整。因此,我们通过修补库的源代码来修复这些问题。虽然这种方法较为脆弱,可能会随着库源代码随时间变化而失效,但目标是在社区的帮助下维护本仓库,使补丁保持最新。
开箱即用的 Puppeteer 和 Playwright 存在一些容易被检测到的明显泄漏。无论你的代理、指纹和行为脚本有多好,如果没有打补丁,对于任何大型网站来说,你就是一个巨大的危险信号。
🕵️ 你可以使用 rebrowser-bot-detector(源代码和详细信息)轻松测试你的自动化设置,以应对现代主要检测手段。
| 打补丁前 👎 | 打补丁后 👍 |
|---|---|
![]() | ![]() |
如果你不想处理补丁和所有可能的错误,有一个即插即用的解决方案。这些包只是在原始代码之上应用了 rebrowser-patches,仅此而已。
Puppeteer:rebrowser-puppeteer(源代码镜像)和 rebrowser-puppeteer-core(源代码镜像)
Playwright(Node.js):rebrowser-playwright(源代码镜像)和 rebrowser-playwright-core(源代码镜像)
Playwright(Python):rebrowser-playwright(源代码镜像)
开始使用它们的最简单方法是以原始包名(npm 别名)安装它们。这样,你无需更改自动化的任何源代码。只安装你的项目已经使用的包:
# Puppeteer
npm install puppeteer@npm:rebrowser-puppeteer puppeteer-core@npm:rebrowser-puppeteer-core
# Playwright
npm install playwright@npm:rebrowser-playwright playwright-core@npm:rebrowser-playwright-core
npm 会安装最新版本,并将其以 "puppeteer": "npm:rebrowser-puppeteer@^…" 的形式保存到 package.json 中。使用 yarn 或 pnpm 时,用相同的参数运行 yarn add 或 pnpm add。
另一种方式是直接使用新的包名:安装 rebrowser-puppeteer 和 rebrowser-puppeteer-core(或 rebrowser-playwright 和 rebrowser-playwright-core)来替代原始包,然后在导入语句中将 puppeteer 替换为 rebrowser-puppeteer(以此类推)。
对于 Python,运行 pip install rebrowser-playwright,并从 rebrowser_playwright 而非 playwright 导入,例如 from rebrowser_playwright.sync_api import sync_playwright。
这些包的版本号跟随原始库的版本号。针对已发布版本的修复会以 X.Y.100、X.Y.101 等版本号发布,因此请始终安装最新版本,而不是匹配原始包的版本号。
🚀 就是这样!只需访问 rebrowser-bot-detector 页面,测试你打过补丁的浏览器即可。
注意事项:
rebrowser-puppeteer 会在安装时下载 Chrome,rebrowser-playwright 需要运行 npx playwright install chromium(或者使用 executablePath / channel: 'chrome' 指向你已有的 Chrome)。rebrowser-puppeteer 和 rebrowser-playwright 以真实名称依赖 rebrowser-puppeteer-core / rebrowser-playwright-core。更早的版本使用了 npm 别名,当同一项目中安装了相同版本的原始 puppeteer / playwright 时,npm 会悄悄让替代包使用未打补丁的核心(#74)。我们的目标是维护并支持这些替代包的最新版本,但我们主要关注较新的版本,所以如果你还在使用 90 年代初的 puppeteer 13.3.7,现在可能是升级的好时机。它很可能不会真正破坏任何东西,因为 API 长期以来相当稳定。
Runtime.Enable 泄漏流行的自动化库依赖 CDP 命令 Runtime.Enable,它允许接收来自 Runtime. 域的事件。这对于管理用于在页面上执行 JavaScript 的执行上下文至关重要,而这是任何自动化流程的关键功能。
然而,存在一种技术可以检测该命令的使用情况,从而揭示浏览器正被 Puppeteer 或 Playwright 等自动化软件控制。这种技术被所有主流反机器人软件使用,例如 Cloudflare、DataDome 等。
我们准备了一篇关于此次泄漏调查的完整文章,你可以在我们的博客中阅读。
有关此技术的更多细节,请阅读 DataDome 的博客文章:How New Headless Chrome & the CDP Signal Are Impacting Bot Detection。
简而言之,就是页面上有几行 JavaScript 代码,如果使用了 Runtime.Enable,这些代码就会被自动调用。
我们的修复方案在每个 frame 上禁用自动的 Runtime.Enable 命令。取而代之的是,当 frame 创建时,我们手动创建具有未知 ID 的上下文。然后,当需要执行代码时,有多种方式可以获取上下文 ID。
addBinding,默认)。该补丁在隔离世界中读取 frame 的 document,在 frame 的主世界中重新解析该节点,并从结果中获取上下文 ID。页面中不会运行任何东西,也不会向页面添加任何东西。只有当该查找失败时,才会回退到原始技术:在主世界中创建一个 binding,调用它并保存其上下文 ID。回退方案会自行清理,但页面可能会短暂看到一个具有随机名称的全局变量。
🟢 优点:这是终极方案,既能保持对主世界的访问,又能与 Web Worker 和 iframe 配合工作。你无需改动任何现有代码库。
🔴 缺点:目前尚未发现。
Page.createIsolatedWorld 创建一个新的隔离上下文,并保存其 ID。🟢 优点:你的所有代码都将在独立的隔离世界中执行,从而防止页面脚本通过 MutationObserver 及其他技术检测到你的改动。
🔴 缺点:你将无法访问主上下文的变量和代码。虽然某些用例确实需要这样做,但隔离上下文在大多数场景下通常都能正常工作。此外,Web Worker 不允许创建新的世界,因此你无法在 Worker 内部执行代码。这是一个小众用例,但在某些情况下可能很重要。针对此问题有一个变通方案,请阅读 How to Access Main Context Objects from Isolated Context in Puppeteer & Playwright。
Runtime.Enable,然后立即调用 Runtime.Disable。这会触发 Runtime.executionContextCreated 事件,使我们能够捕获正确的上下文 ID。
🟢 优点:你将拥有对主上下文的完全访问权限。
🔴 缺点:在这段短暂的时间窗口内,页面有一定概率会调用导致泄漏的代码。风险较低,因为检测代码通常会在特定操作期间被调用,例如 CAPTCHA 页面或登录/注册表单,通常就在页面加载之后。你的业务逻辑通常会在稍后调用。
🎉 我们的测试表明,目前 Cloudflare 或 DataDome 均无法检测到上述所有方案。
注意:你可以使用环境变量即时更改此补丁的设置。这样你就可以根据业务逻辑轻松地在已修补和未修补版本之间切换。
REBROWSER_PATCHES_RUNTIME_FIX_MODE=addBinding — addBinding 技术(默认)。保持主世界访问权限,并可与 iframe 和 Web Worker 配合工作。REBROWSER_PATCHES_RUNTIME_FIX_MODE=alwaysIsolated — 始终在隔离上下文中运行所有脚本。页面脚本无法观察你的执行,但你会失去主世界访问权限、page.exposeFunction() 以及(Puppeteer)Web Worker。REBROWSER_PATCHES_RUNTIME_FIX_MODE=enableDisable — 使用 Enable/Disable 技术。不推荐: 它仍会在短暂窗口内调用 Runtime.enable,因此并非完全无泄漏。仅在 addBinding 在特定页面上失败时才使用它。REBROWSER_PATCHES_RUNTIME_FIX_MODE=0 — 完全禁用针对此泄漏的修复REBROWSER_PATCHES_DEBUG=1 — 启用一些调试消息请记住,你可以通过不同方式设置这些变量,例如在代码中:
process.env.REBROWSER_PATCHES_RUNTIME_FIX_MODE = "alwaysIsolated"
或在命令行中:
REBROWSER_PATCHES_RUNTIME_FIX_MODE=alwaysIsolated node app.js
默认情况下,Puppeteer 会在 page.evaluate() 中的每个脚本里添加 //# sourceURL=pptr:...,而 Playwright 则通过一个名为 UtilityScript 的辅助类来运行 page.evaluate()。如果页面在你的代码运行期间获取 new Error().stack(例如通过你的代码所触及的 getter),它就能看到这些名称,从而知道自身正被自动化控制。
Puppeteer 补丁完全不添加 sourceURL,因此堆栈帧会像其他注入脚本一样显示为 <anonymous>。Playwright 补丁则将该辅助类重命名为每个进程随机选取的短名称,并偏移其行号,因此不存在可供查找的固定名称或位置。你可以通过环境变量进行调整:
# Puppeteer only: use a sourceURL of your choice. Prefer a full URL: a bare file name such as
# jquery.min.js shows up in stack traces as a script with no address, which detectors can flag
REBROWSER_PATCHES_SOURCE_URL=https://example.com/js/app.js
# use 0 to completely disable this patch (Puppeteer and Playwright)
REBROWSER_PATCHES_SOURCE_URL=0
navigator.webdriver由 Puppeteer 或 Playwright 启动的 Chrome 会报告 navigator.webdriver = true — 这是一个明显的自动化标志,许多反机器人系统都会检查它。此补丁将 --disable-blink-features=AutomationControlled 添加到默认启动参数中,使 navigator.webdriver 保持为 false。你自己传入的任何 --disable-blink-features=... 都会被合并进来,而不是被覆盖。
Puppeteer 还会传入 --enable-automation,这会显示“Chrome 正受到自动测试软件的控制”提示栏。Puppeteer 补丁会移除它(Playwright 从 1.64 起已不再传入)。