CloakBrowser 验证码解决工具：如何将 CapSolver 与 Playwright 浏览器自动化集成

简要说明

• CloakBrowser 通过 Playwright 兼容的 Python API 启动 Chromium 构建；CapSolver 处理 CAPTCHA 任务并返回令牌或图像识别结果。
• CloakBrowser 不是 CAPTCHA 解决服务。集成保持浏览器状态在 CloakBrowser 中，仅将所需的挑战参数发送到 CapSolver，并通过相同的 Playwright 页面提交结果。
• 对于现有的 Playwright 脚本，主要的浏览器端更改是将标准 Chromium 启动器替换为 from cloakbrowser import launch。
• 在挑战与当前会话相关时，保持页面 URL、站点密钥、代理、cookies、语言环境和用户代理一致。
• 返回的令牌是中间结果。只有在目标页面或授权应用程序接受它后，才将工作流视为成功。

CloakBrowser 和 CapSolver 的作用

CloakBrowser 是一个基于 Chromium 的浏览器包，用于 Playwright 和 Puppeteer 自动化。其官方仓库描述了浏览器信号的源级更改，如 canvas、WebGL、音频、字体、GPU、屏幕、WebRTC 和自动化相关行为。Python 启动器返回一个标准的 Playwright Browser，因此熟悉的方法如 new_page()、定位器、evaluate()、点击和表单操作仍然可用。

CloakBrowser 不解决 CAPTCHA。CapSolver 提供该独立服务：您的应用程序创建一个包含挑战参数的任务，接收解决方案，并使用当前页面提交它。这种边界很重要，因为浏览器环境管理和 CAPTCHA 处理有不同的输入和失败模式。

职责如下：

CloakBrowser
  -> 启动 Chromium 并维护 cookies、代理、页面和浏览器上下文
  -> 读取当前会话显示的挑战参数

CapSolver
  -> 接收支持的任务类型和所需的挑战参数
  -> 返回令牌或图像识别结果

Playwright API
  -> 将结果放回同一页面
  -> 调用预期的回调或提交表单
  -> 验证最终页面或应用程序响应

如果您需要在集成这两个服务之前重新熟悉 Playwright，请参阅 CapSolver 的 Playwright 术语表 和 Playwright 浏览器自动化指南。

前提条件

仅在您拥有或被授权测试或自动化的网站和应用程序上使用此工作流。您需要：

• Python 3.9 或更高版本；
• CloakBrowser 的安装和许可证或受支持的评估设置；
• CapSolver 账户和 API 密钥；
• 您被授权自动化的页面的目标 URL 和挑战参数。

安装 Python 包：

pip install cloakbrowser capsolver

对于 CloakBrowser 许可证，当前仓库记录了 cloakbrowser login 的交互式设置和 CLOAKBROWSER_LICENSE_KEY 环境变量用于 CI 或服务器。将供应商凭证保留在源代码控制之外。环境变量或密钥管理器比提交字面密钥更安全。

第 1 步：使用 Playwright API 启动 CloakBrowser

以下最小示例打开一个页面，读取其标题并关闭浏览器：

from cloakbrowser import launch

browser = launch(
    headless=False,
    humanize=True,
    license_key="cb_...",
)

page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
browser.close()

启动器选项控制浏览器环境：

对于绑定会话的挑战，避免在读取挑战和提交其解决方案之间更改代理、用户代理、cookies 或浏览器上下文。CapSolver 的 网页安全中的浏览器指纹 常见问题解答解释了为什么多个浏览器信号可以一起评估。

第 2 步：创建 CapSolver reCAPTCHA v2 任务

基本的 Python SDK 流程设置 API 密钥并发送支持的任务对象。此示例使用 Google 的公共 reCAPTCHA v2 示例值：

import capsolver

capsolver.api_key = "CAP-..."

solution = capsolver.solve(
    {
        "type": "ReCaptchaV2TaskProxyLess",
        "websiteURL": "https://www.google.com/recaptcha/api2/demo",
        "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    }
)

token = solution.get("gRecaptchaResponse")
if not isinstance(token, str) or not token:
    raise RuntimeError(f"CapSolver 未返回 reCAPTCHA 令牌: {solution}")

print("收到令牌")

重要字段如下：

在生产部署前，请查看当前 CapSolver reCAPTCHA v2 文档，并使用活动页面的值，而不是复制示例参数。更详细的 reCAPTCHA v2 解决指南 覆盖任务选择和响应字段。

领取您的 CapSolver 奖励代码

立即提升您的自动化预算！
在充值 CapSolver 账户时使用奖励代码 CAP26，每次充值可获得额外 5% 奖励 —— 没有限制。
现在在您的 CapSolver 仪表板 中领取

第 3 步：通过同一 CloakBrowser 页面返回令牌

下面的完整示例将导航和令牌提交保留在一个 CloakBrowser 页面内。CSS 选择器和提交行为特定于公共演示；真实应用程序可能使用回调、框架管理的字段或另一个表单流程。

import re

import capsolver
from cloakbrowser import launch


def inject_recaptcha_token(page, token):
    if not isinstance(token, str) or not token:
        raise ValueError("需要非空的 reCAPTCHA 令牌")

    page.evaluate(
        """
        (token) => {
            const textarea = document.getElementById('g-recaptcha-response');
            if (!textarea) {
                throw new Error('未找到 g-recaptcha-response');
            }
            textarea.value = token;
        }
        """,
        token,
    )

    with page.expect_navigation(
        wait_until="domcontentloaded",
        timeout=30_000,
    ):
        page.click("#recaptcha-demo-submit")

    return page.content()


def main():
    capsolver.api_key = "CAP-..."  # 您的 CAPSOLVER API 密钥

    browser = launch(
        license_key="cb_...",  # 您的 CLOAKBROWSER 许可证密钥
        headless=False,
        locale="en-US",
    )

    try:
        page = browser.new_page()
        page.goto(
            "https://www.google.com/recaptcha/api2/demo",
            wait_until="domcontentloaded",
            timeout=60_000,
        )

        solution = capsolver.solve(
            {
                "type": "ReCaptchaV2TaskProxyLess",
                "websiteURL": page.url,
                "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
            }
        )

        token = solution.get("gRecaptchaResponse")
        result_page = inject_recaptcha_token(page, token)

        match = re.search(
            r'<div class="recaptcha-success">(.*?)</div>',
            result_page,
        )
        print(match.group(1) if match else "验证失败")
    finally:
        browser.close()


if __name__ == "__main__":
    main()

作为普通 Python 脚本运行：

python cloakbrowser-capsolver.py

在生产中，从环境变量加载密钥，围绕临时 API 或导航失败添加有界重试，记录 CapSolver 任务 ID 而不记录机密，验证最终业务结果。CapSolver 还提供了关于 将 CAPTCHA 解决方案集成到 Playwright 或 Puppeteer 中的常见问题解答。

第 4 步：使用 ImageToTextTask 处理图像 CAPTCHA

一些授权测试工作流将 CAPTCHA 显示为图像而不是基于令牌的小部件。在这种情况下，捕获或提取图像，将其转换为 Base64（不带 Data URL 前缀），并提交到 ImageToTextTask。

从原始工作流中截取的截图显示了 BotDetect 功能演示 中的图像元素和输入字段：

import capsolver
from cloakbrowser import launch


TARGET_URL = "https://captcha.com/demos/features/captcha-demo.aspx"

browser = launch(headless=False, humanize=True)

try:
    page = browser.new_page()
    page.goto(TARGET_URL, wait_until="domcontentloaded")

    image_src = page.locator("#demoCaptcha_CaptchaImage").get_attribute("src")
    if not image_src or "," not in image_src:
        raise RuntimeError("验证码图像不是 Data URL")

    base64_image = image_src.split(",", 1)[1].replace("\n", "")

    solution = capsolver.solve(
        {
            "type": "ImageToTextTask",
            "websiteURL": page.url,
            "module": "common",
            "body": base64_image,
        }
    )

    text = solution.get("text")
    if not isinstance(text, str) or not text:
        raise RuntimeError(f"CapSolver 未返回 OCR 文本: {solution}")

    page.locator("#captchaCode").fill(text)
    page.locator("#validateCaptchaButton").click()
finally:
    browser.close()

选择器有意绑定到演示页面。检查授权目标页面并使用其实际的图像、输入和提交选择器。

多个图像和数字模块

ImageToTextTask 可以使用不同的模块来处理支持的图像格式。原始文章包含此模块概述，此处保留以供参考：

当支持的模块接受多个图像时，发送该模块记录的数组并读取相应的答案：

solution = capsolver.solve(
    {
        "type": "ImageToTextTask",
        "module": "number",
        "images": [base64_image],
    }
)

answers = solution["answers"]

模块名称、请求字段和支持的格式可能会更改，因此请根据当前 ImageToTextTask 文档 进行验证。有关更广泛的 Python API 模式，请参阅 如何在 Python 中集成 CAPTCHA 解决方案 API。

reCAPTCHA v3 有什么变化？

浏览器架构保持不变，但 CapSolver 任务和页面参数必须与 v3 实现匹配。特别是：

1. 使用 CapSolver 记录的支持 reCAPTCHA v3 任务类型。
2. 在集成使用时提供页面预期的操作值。
3. 从活动页面而不是无关示例中读取 URL 和站点密钥。
4. 保持结果令牌在同一个浏览器会话中并在其过期前提交。
5. 验证应用程序响应。API 返回的分数或令牌不一定保证目标应用程序接受请求。

不要仅为了提交令牌而打开没有原始 cookies 和会话状态的新页面。这会破坏目标应用程序可能用于评估结果的上下文。

解决 CloakBrowser 和 CapSolver 的问题

脚本启动了标准的 Playwright Chromium

此代码启动的是 Playwright 的捆绑 Chromium，而不是 CloakBrowser：

from playwright.sync_api import sync_playwright

pw = sync_playwright().start()
browser = pw.chromium.launch()

改用 CloakBrowser 的启动器：

from cloakbrowser import launch

browser = launch()

根据 CloakBrowser 仓库，playwright install-deps chromium 在 Linux 上当缺少共享系统库时可能有用。运行 playwright install chromium 是不同的：它下载 Playwright 的浏览器，不会修复 CloakBrowser 的启动路径。

CapSolver 返回令牌，但页面拒绝它

按顺序检查每个边界：

• websiteURL 是活动页面使用的完整 URL；
• websiteKey 属于该页面；
• 选择的任务类型和可选操作与挑战匹配；
• 令牌写入预期字段或传递给页面的回调；
• 页面未刷新或替换挑战；
• cookies、代理、用户代理和浏览器上下文保持一致；
• 最终页面或应用程序响应确认接受。

图像任务返回无文本

确认图像正文是有效的 Base64，已移除 Data URL 前缀，所选模块支持图像，并且响应字段与当前文档匹配。捕获 CapSolver 错误代码和任务 ID 以进行调试，但不要记录 API 密钥或敏感页面数据。

提交后导航无限等待

并非每次提交都会导致完整导航。某些网站更新 DOM 或进行 XHR 请求。将 expect_navigation() 替换为实际表示成功的条件：定位器变为可见、URL 更改、响应事件或应用程序特定的状态元素。 Playwright 官方 Browser API 参考 是当前 API 行为的最佳来源。

负责任且可靠的自动化

CAPTCHA系统是访问控制和滥用预防机制。仅在您拥有所有权或明确授权测试的系统上，使用CapSolver和CloakBrowser进行合法的自动化操作。尊重网站条款、速率限制、隐私要求和适用法律。不要使用自动化访问私人数据、创建滥用流量或干扰其他用户。

对于质量保证和监控，当可用时优先使用专用测试环境和供应商测试密钥。记录页面URL、任务类型、任务ID、经过时间以及最终应用状态，以便追踪失败情况，同时不要存储凭据或个人数据。CAPTCHA自动化用于质量保证测试的指南提供了更多用于受控测试工作流的模式。

使用CapSolver构建可靠的自动化工作流

CloakBrowser可以提供Playwright兼容的浏览器环境，而CapSolver处理支持的CAPTCHA任务。将这些职责分开可以使工作流更易于测试：从当前页面读取挑战，请求匹配的解决方案，在同一上下文中提交，并验证应用结果。

尝试CapSolver用于授权的CloakBrowser或Playwright工作流，并在将演示代码移至生产环境之前查阅当前文档。

常见问题

问：CloakBrowser是CAPTCHA求解器吗？

不。CloakBrowser提供Chromium浏览器和Playwright兼容的自动化接口。支持的CAPTCHA任务由类似CapSolver的独立服务处理。

问：现有的Playwright脚本可以使用CloakBrowser吗？

通常可以。将浏览器启动路径替换为from cloakbrowser import launch，然后继续使用返回的Playwright Browser、页面、定位器和评估方法。在您的环境中测试浏览器特定的选项和依赖项。

问：为什么必须在同一个浏览器上下文中提交CAPTCHA结果？

目标应用程序可能将挑战与cookie、代理地址、浏览器信号、URL或其他会话数据相关联。切换上下文可能导致原本有效的挑战参数不一致。

问：在哪里可以找到reCAPTCHA网站密钥？

使用您被授权自动化的页面中配置的密钥。它可能出现在小部件标记或页面脚本中。不要从无关教程或域名中复制密钥。

问：CapSolver令牌是否保证成功？

不。令牌是中间结果。最终的成功条件是正确且及时提交令牌后目标页面或应用的响应。

问：此集成能否处理图像CAPTCHAs？

CapSolver的ImageToTextTask支持文档化的图像识别模块。提取授权页面的图像，发送所需的Base64负载，并通过同一CloakBrowser页面输入返回的文本。

问：API和许可证密钥应出现在脚本中吗？

不。示例使用可识别的占位符。生产代码应从环境变量或密钥管理器中读取机密信息，并且绝不能将其提交到源代码控制中。

问：如何安全地测试此集成？

从供应商演示或您控制的应用程序开始。使用有限的请求速率，记录任务ID和最终结果，并在您获得授权并明确操作需求后才移至生产站点。