如何使用 Botasaurus 和 CapSolver 在 Python 中解决 CAPTCHAs（完整指南）

如何使用Botasaurus和CapSolver在Python中解决CAPTCHA（完整指南）

Ethan Collins

Pattern Recognition Specialist

15-Dec-2025

TLDR： 本指南展示了如何将 Botasaurus（一个带有内置反检测功能的 Python 网页抓取框架）与 CapSolver（一个验证码解决 API）结合使用，以在大规模网页抓取过程中自动绕过 reCAPTCHA v2、reCAPTCHA v3 和 Cloudflare Turnstile。核心流程包括设置环境、使用 CapSolver 浏览器扩展识别验证码参数、通过 Python 辅助函数调用 CapSolver API 获取解决方案令牌，最后使用 Botasaurus 将令牌注入网页以提交表单。

如何使用 Botasaurus 和 CapSolver 解决 CAPTCHA（完整指南）

大规模网页抓取时经常会遇到阻止自动化访问的验证码。本指南展示了如何将 Botasaurus（一个强大的网页抓取框架）与 CapSolver 结合，自动解决 reCAPTCHA v2、reCAPTCHA v3 和 Cloudflare Turnstile 验证码。

什么是 Botasaurus？

Botasaurus 是一个 Python 网页抓取框架，通过内置的反检测功能简化浏览器自动化。它提供了一个基于装饰器的 API 来处理浏览器任务。

核心功能：

反检测：内置的隐身功能以避免被识别为机器人
简单 API：基于装饰器的接口，使用 @browser
JavaScript 执行：在浏览器上下文中运行自定义 JS 代码
元素选择：使用 CSS 选择器轻松操作 DOM

安装：

bash 复制代码

pip install botasaurus

基本用法：

python 复制代码

from botasaurus.browser import browser, Driver

@browser()
def scrape_page(driver: Driver, data):
    driver.get("https://example.com")
    title = driver.get_text("h1")
    return {"title": title}

# 运行爬虫
result = scrape_page()

什么是 CapSolver？

CapSolver 是一个验证码解决服务，提供 API 来解决各种验证码类型，包括 reCAPTCHA 和 Cloudflare Turnstile。

支持的验证码类型：

reCAPTCHA v2（复选框和不可见）
reCAPTCHA v3（基于分数）
reCAPTCHA 企业版
Cloudflare Turnstile
更多

获取 API 密钥：

在 CapSolver 仪表板注册账户
向账户充值
复制你的 API 密钥（以 CAP- 开头）

项目设置

安装依赖

bash 复制代码

pip install botasaurus capsolver requests python-dotenv

配置环境

在项目根目录创建一个 .env 文件：

env 复制代码

CAPSOLVER_API_KEY=CAP-YOUR_API_KEY_HERE

配置模块

创建一个共享的配置加载器：

python 复制代码

# shared/config.py
import os
from pathlib import Path
from dotenv import load_dotenv

# 从项目根目录加载.env文件
ROOT_DIR = Path(__file__).parent.parent
load_dotenv(ROOT_DIR / ".env")

class Config:
    """CapSolver 集成的配置类。"""

    # CapSolver API 密钥
    CAPSOLVER_API_KEY: str = os.getenv("CAPSOLVER_API_KEY", "")

    # CapSolver API 端点
    CAPSOLVER_API_URL = "https://api.capsolver.com"
    CREATE_TASK_ENDPOINT = f"{CAPSOLVER_API_URL}/createTask"
    GET_RESULT_ENDPOINT = f"{CAPSOLVER_API_URL}/getTaskResult"

    @classmethod
    def validate(cls) -> bool:
        """检查配置是否有效。"""
        if not cls.CAPSOLVER_API_KEY:
            print("错误：未设置 CAPSOLVER_API_KEY！")
            return False
        return True

使用 CapSolver 扩展识别验证码参数

在与 API 集成之前，你需要识别目标验证码的正确参数。CapSolver 浏览器扩展可以自动检测所有必需的参数。

安装

从 Chrome Web Store 安装 CapSolver 扩展。

使用验证码检测器

按 F12 打开开发者工具
导航到 Capsolver 验证码检测器 标签页
在访问目标网站时保持检测器面板打开
触发页面上的验证码

重要提示： 在触发验证码之前不要关闭 CapSolver 面板，否则会清除之前检测到的信息。

检测到的参数

扩展会自动识别所有必需的 reCAPTCHA 参数：

网站 URL
站点密钥
pageAction（用于 v3）
isInvisible
isEnterprise
Api 域名

检测器提供格式化的 JSON 输出，方便 API 集成，轻松复制解决任务所需的精确参数。

更多详情请参阅如何识别验证码参数的完整指南。

使用 CapSolver API 解决 reCAPTCHA v2

reCAPTCHA v2 是经典的“我不是机器人”复选框验证码。它可能会向用户展示图像选择挑战。

查找站点密钥

你可以使用 CapSolver 扩展检测器（如上所述）或手动查找：

在页面 HTML 中查找：

html 复制代码

<div class="g-recaptcha" data-sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"></div>

或在 JavaScript 中查找：

javascript 复制代码

grecaptcha.render('container', {'sitekey': '6Le-xxxxx...'});

辅助函数

python 复制代码

# utils/capsolver_helper.py
import time
import requests
from shared.config import Config

def solve_recaptcha_v2(
    website_url: str,
    website_key: str,
    is_invisible: bool = False,
    timeout: int = 120
) -> dict:
    """
    使用 CapSolver API 解决 reCAPTCHA v2。

    Args:
        website_url: 包含验证码的页面 URL
        website_key: reCAPTCHA 站点密钥
        is_invisible: 是否为不可见 reCAPTCHA v2
        timeout: 等待解决方案的最大时间（秒）

    Returns:
        包含 'gRecaptchaResponse' 令牌的字典
    """

    if not Config.validate():
        raise Exception("配置无效 - 检查你的 API 密钥")

    # 构建任务负载
    task = {
        "type": "ReCaptchaV2TaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    if is_invisible:
        task["isInvisible"] = True

    payload = {
        "clientKey": Config.CAPSOLVER_API_KEY,
        "task": task
    }

    # 创建任务
    response = requests.post(Config.CREATE_TASK_ENDPOINT, json=payload)
    result = response.json()

    if result.get("errorId") and result.get("errorId") != 0:
        raise Exception(f"创建任务失败: {result.get('errorDescription')}")

    task_id = result.get("taskId")

    # 轮询结果
    start_time = time.time()
    while time.time() - start_time < timeout:
        time.sleep(2)

        result_payload = {
            "clientKey": Config.CAPSOLVER_API_KEY,
            "taskId": task_id
        }

        response = requests.post(Config.GET_RESULT_ENDPOINT, json=result_payload)
        result = response.json()

        if result.get("status") == "ready":
            return result.get("solution", {})

        elif result.get("status") == "failed":
            raise Exception(f"任务失败: {result.get('errorDescription')}")

    raise Exception(f"超时 {timeout} 秒后")

完整的 reCAPTCHA v2 示例

python 复制代码

from botasaurus.browser import browser, Driver
from shared.config import Config
from utils.capsolver_helper import solve_recaptcha_v2

DEMO_URL = "https://www.google.com/recaptcha/api2/demo"
DEMO_SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"

@browser(headless=False)
def solve_recaptcha_v2_with_api(driver: Driver, data: dict):
    """使用 CapSolver API 解决 reCAPTCHA v2 并注入令牌。"""

    url = data.get("url", DEMO_URL)
    site_key = data.get("site_key", DEMO_SITEKEY)

    # 步骤 1：加载页面
    driver.get(url)
    driver.sleep(2)

    # 步骤 2：从页面中提取站点密钥（可选）
    extracted_key = driver.run_js("""
        const recaptchaDiv = document.querySelector('.g-recaptcha');
        return recaptchaDiv ? recaptchaDiv.getAttribute('data-sitekey') : null;
    """)

    if extracted_key:
        site_key = extracted_key

    # 步骤 3：通过 CapSolver API 解决验证码
    solution = solve_recaptcha_v2(
        website_url=url,
        website_key=site_key
    )

    token = solution.get("gRecaptchaResponse")

    # 步骤 4：将令牌注入页面
    driver.run_js(f"""
        // 设置隐藏文本区域的值
        const responseField = document.querySelector('[name="g-recaptcha-response"]');
        if (responseField) {{
            responseField.value = "{token}";
        }}

        // 如果可用，触发回调
        if (typeof ___grecaptcha_cfg !== 'undefined') {{
            try {{
                const clients = ___grecaptcha_cfg.clients;
                for (const key in clients) {{
                    const client = clients[key];
                    if (client && client.callback) {{
                        client.callback("{token}");
                    }}
                }}
            }} catch (e) {{}}
        }}
    """)

    # 步骤 5：提交表单
    submit_button = driver.select('input[type="submit"]')
    if submit_button:
        submit_button.click()
        driver.sleep(2)

    return {"success": True, "token_length": len(token)}

# 运行演示
result = solve_recaptcha_v2_with_api(data={"url": DEMO_URL, "site_key": DEMO_SITEKEY})

使用 CapSolver API 解决 reCAPTCHA v3

reCAPTCHA v3 是不可见的，并通过分析用户行为生成 0.0 到 1.0 之间的分数。

与 v2 的关键区别： reCAPTCHA v3 需要 pageAction 参数。

查找 pageAction

查找 pageAction 最简单的方法是使用 CapSolver 扩展检测器。或者在页面 JavaScript 中查找：

javascript 复制代码

grecaptcha.execute('siteKey', {action: 'login'})
// 'login' 是你的 pageAction

辅助函数

python 复制代码

def solve_recaptcha_v3(
    website_url: str,
    website_key: str,
    page_action: str,
    timeout: int = 120
) -> dict:
    """
    使用 CapSolver API 解决 reCAPTCHA v3。

    Args:
        website_url: 包含验证码的页面 URL
        website_key: reCAPTCHA 站点密钥
        page_action: 动作参数（v3 必填）
        timeout: 等待解决方案的最大时间（秒）

    Returns:
        包含 'gRecaptchaResponse' 令牌的字典
    """

    if not Config.validate():
        raise Exception("配置无效 - 检查你的 API 密钥")

    if not page_action:
        raise Exception("pageAction 是 reCAPTCHA v3 的必需参数")

    # 构建任务负载
    task = {
        "type": "ReCaptchaV3TaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
        "pageAction": page_action,  # v3 必填
    }

    payload = {
        "clientKey": Config.CAPSOLVER_API_KEY,
        "task": task
    }

    # 创建任务
    response = requests.post(Config.CREATE_TASK_ENDPOINT, json=payload)
    result = response.json()

    if result.get("errorId") and result.get("errorId") != 0:
        raise Exception(f"创建任务失败: {result.get('errorDescription')}")

    task_id = result.get("taskId")

    # 轮询结果
    start_time = time.time()
    while time.time() - start_time < timeout:
        time.sleep(2)

        result_payload = {
            "clientKey": Config.CAPSOLVER_API_KEY,
            "taskId": task_id
        }

        response = requests.post(Config.GET_RESULT_ENDPOINT, json=result_payload)
        result = response.json()

        if result.get("status") == "ready":
            return result.get("solution", {})

        elif result.get("status") == "failed":
            raise Exception(f"任务失败: {result.get('errorDescription')}")

    raise Exception(f"超时 {timeout} 秒后")

完整的 reCAPTCHA v3 示例

python 复制代码

from botasaurus.browser import browser, Driver
from shared.config import Config
from utils.capsolver_helper import solve_recaptcha_v3

DEMO_URL = "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php"
DEMO_SITEKEY = "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696"
PAGE_ACTION = "examples/v3scores"

@browser(headless=False)
def solve_recaptcha_v3_with_api(driver: Driver, data: dict):
    """使用 CapSolver API 解决 reCAPTCHA v3 并注入令牌。"""

    url = data.get("url", DEMO_URL)
    site_key = data.get("site_key", DEMO_SITEKEY)
    page_action = data.get("page_action", PAGE_ACTION)

    # 步骤 1：加载页面
    driver.get(url)
    driver.sleep(2)

    # 步骤 2：通过 CapSolver API 解决验证码
    solution = solve_recaptcha_v3(
        website_url=url,
        website_key=site_key,
        page_action=page_action
    )

    token = solution.get("gRecaptchaResponse")

    # 步骤 3：将令牌注入页面
    driver.run_js(f"""
        const token = "{token}";

        // 如果存在，设置隐藏字段
        const responseField = document.querySelector('[name="g-recaptcha-response"]');
        if (responseField) {{
            responseField.value = token;
        }}

        // 如果表单存在但字段不存在，则创建隐藏字段
        const forms = document.querySelectorAll('form');
        forms.forEach(form => {{
            let field = form.querySelector('[name="g-recaptcha-response"]');
            if (!field) {{
                field = document.createElement('input');
                field.type = 'hidden';
                field.name = 'g-recaptcha-response';
                form.appendChild(field);
            }}
            field.value = token;
        }});
    """)

    # 步骤 4：提交或验证
    buttons = driver.select_all("button")
    for button in buttons:
        if "verify" in button.text.lower() or "submit" in button.text.lower():
            button.click()
            driver.sleep(2)
            break

    return {"success": True, "token_length": len(token)}

# 运行演示
result = solve_recaptcha_v3_with_api(data={
    "url": DEMO_URL,
    "site_key": DEMO_SITEKEY,
    "page_action": PAGE_ACTION
})

使用 CapSolver API 解决 Cloudflare Turnstile

Cloudflare Turnstile 是一种注重隐私的验证码替代方案，旨在比传统验证码更不侵入用户。

与 reCAPTCHA 的关键区别：

任务类型是 AntiTurnstileTaskProxyLess
响应字段是 token（不是 gRecaptchaResponse）
站点密钥通常以 0x4 开头

查找站点密钥

在页面 HTML 中查找：

html 复制代码

<div class="cf-turnstile" data-sitekey="0x4AAAAAAABS7vwvV6VFfMcD"></div>

辅助函数

python 复制代码

def solve_turnstile(
    website_url: str,
    website_key: str,
    action: str = None,
    cdata: str = None,
    timeout: int = 120
) -> dict:
    """使用 CapSolver API 解决 Cloudflare Turnstile 验证码。"""
使用 CapSolver API 解决 Cloudflare Turnstile。

    参数:
        website_url: 包含 Turnstile 的页面的 URL
        website_key: Turnstile 站点密钥（以 0x4 开头）
        action: 可选的 data-action 属性中的 action
        cdata: 可选的 data-cdata 属性中的 cdata
        timeout: 等待解决方案的最大时间（秒）

    返回:
        包含 'token' 字段的字典
    """

    if not Config.validate():
        raise Exception("配置无效 - 检查您的 API 密钥")

    # 构建任务负载
    task = {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": website_url,
        "websiteKey": website_key,
    }

    # 添加可选的元数据
    metadata = {}
    if action:
        metadata["action"] = action
    if cdata:
        metadata["cdata"] = cdata

    if metadata:
        task["metadata"] = metadata

    payload = {
        "clientKey": Config.CAPSOLVER_API_KEY,
        "task": task
    }

    # 创建任务
    response = requests.post(Config.CREATE_TASK_ENDPOINT, json=payload)
    result = response.json()

    if result.get("errorId") and result.get("errorId") != 0:
        raise Exception(f"创建任务失败: {result.get('errorDescription')}")

    task_id = result.get("taskId")

    # 轮询结果
    start_time = time.time()
    while time.time() - start_time < timeout:
        time.sleep(2)

        result_payload = {
            "clientKey": Config.CAPSOLVER_API_KEY,
            "taskId": task_id
        }

        response = requests.post(Config.GET_RESULT_ENDPOINT, json=result_payload)
        result = response.json()

        if result.get("status") == "ready":
            return result.get("solution", {})

        elif result.get("status") == "failed":
            raise Exception(f"任务失败: {result.get('errorDescription')}")

    raise Exception(f"超时，等待了 {timeout} 秒")

完整的 Turnstile 示例

python 复制代码

from botasaurus.browser import browser, Driver
from shared.config import Config
from utils.capsolver_helper import solve_turnstile

DEMO_URL = "https://peet.ws/turnstile-test/non-interactive.html"
DEMO_SITEKEY = "0x4AAAAAAABS7vwvV6VFfMcD"

@browser(headless=False)
def solve_turnstile_with_api(driver: Driver, data: dict):
    """使用 CapSolver API 解决 Cloudflare Turnstile 并注入令牌。"""

    url = data.get("url", DEMO_URL)
    site_key = data.get("site_key", DEMO_SITEKEY)

    # 步骤 1: 加载页面
    driver.get(url)
    driver.sleep(3)

    # 步骤 2: 从页面中提取站点密钥（可选）
    extracted_params = driver.run_js("""
        const turnstileDiv = document.querySelector('.cf-turnstile, [data-sitekey]');
        if (turnstileDiv) {
            const key = turnstileDiv.getAttribute('data-sitekey');
            if (key && key.startsWith('0x')) {
                return {
                    sitekey: key,
                    action: turnstileDiv.getAttribute('data-action')
                };
            }
        }
        return null;
    """)

    if extracted_params and extracted_params.get("sitekey"):
        site_key = extracted_params["sitekey"]

    # 步骤 3: 通过 CapSolver API 解决 Turnstile
    solution = solve_turnstile(
        website_url=url,
        website_key=site_key,
        action=extracted_params.get("action") if extracted_params else None
    )

    token = solution.get("token")

    # 步骤 4: 将令牌注入页面
    driver.run_js(f"""
        const token = "{token}";

        // 找到并填写 cf-turnstile-response 字段
        const responseFields = [
            document.querySelector('[name="cf-turnstile-response"]'),
            document.querySelector('[name="cf_turnstile_response"]'),
            document.querySelector('input[name*="turnstile"]')
        ];

        for (const field of responseFields) {{
            if (field) {{
                field.value = token;
                break;
            }}
        }}

        // 如果表单存在但字段不存在，则创建隐藏字段
        const forms = document.querySelectorAll('form');
        forms.forEach(form => {{
            let field = form.querySelector('[name="cf-turnstile-response"]');
            if (!field) {{
                field = document.createElement('input');
                field.type = 'hidden';
                field.name = 'cf-turnstile-response';
                form.appendChild(field);
            }}
            field.value = token;
        }});
    """)

    # 步骤 5: 提交表单
    submit_btn = driver.select('button[type="submit"], input[type="submit"]')
    if submit_btn:
        submit_btn.click()
        driver.sleep(2)

    return {"success": True, "token_length": len(token)}

# 运行示例
result = solve_turnstile_with_api(data={"url": DEMO_URL, "site_key": DEMO_SITEKEY})

任务类型参考

验证码类型	任务类型	响应字段	必需参数
reCAPTCHA v2	`ReCaptchaV2TaskProxyLess`	`gRecaptchaResponse`	`websiteURL`, `websiteKey`
reCAPTCHA v2 企业版	`ReCaptchaV2EnterpriseTaskProxyLess`	`gRecaptchaResponse`	`websiteURL`, `websiteKey`
reCAPTCHA v3	`ReCaptchaV3TaskProxyLess`	`gRecaptchaResponse`	`websiteURL`, `websiteKey`, `pageAction`
reCAPTCHA v3 企业版	`ReCaptchaV3EnterpriseTaskProxyLess`	`gRecaptchaResponse`	`websiteURL`, `websiteKey`, `pageAction`
Cloudflare Turnstile	`AntiTurnstileTaskProxyLess`	`token`	`websiteURL`, `websiteKey`

对于阻止数据中心 IP 的网站，请使用代理变体（例如 ReCaptchaV2Task）并提供您自己的住宅代理。

最佳实践

1. 令牌过期

验证码令牌会很快过期（通常在 2 分钟内）。收到令牌后应立即使用：

python 复制代码

# 获取令牌
solution = solve_recaptcha_v2(url, site_key)
token = solution.get("gRecaptchaResponse")

# 立即使用 - 不要保存以备后用
driver.run_js(f'document.querySelector("[name=g-recaptcha-response]").value = "{token}"')
driver.select('button[type="submit"]').click()

2. 错误处理

始终实现适当的 API 失败处理逻辑：

python 复制代码

try:
    solution = solve_recaptcha_v2(url, site_key)
except Exception as e:
    print(f"验证码解决失败: {e}")
    # 实现重试逻辑或备用方案

3. 限速

在请求之间添加延迟以避免触发反机器人措施：

python 复制代码

driver.sleep(2)  # 页面加载后等待
# ... 解决验证码 ...
driver.sleep(1)  # 表单提交前等待

4. 配置验证

在发出请求前始终验证您的 API 密钥：

python 复制代码

if not Config.validate():
    raise Exception("请在 .env 文件中配置您的 API 密钥")

结论

将 Botasaurus 与 CapSolver 结合使用，为网络爬虫项目中的验证码提供了一个强大的解决方案。基于 API 的方法让您完全控制解决过程，并在不同验证码类型中可靠运行。

立即提升您的自动化预算！
在为 CapSolver 账户充值时使用优惠码 CAPN，每次充值可获得额外 5% 奖励 —— 没有上限。
现在在您的 CapSolver 仪表板兑换

关键要点

Botasaurus 提供了带有内置反检测功能的浏览器自动化
CapSolver API 提供了一种程序化解决多种验证码类型的方法
reCAPTCHA v2 需要 websiteURL 和 websiteKey 参数
reCAPTCHA v3 额外需要 pageAction 参数
Cloudflare Turnstile 返回 token 字段而不是 gRecaptchaResponse
令牌有效期很短（约 2 分钟），因此在收到后应立即使用

常见问题（FAQ）

如何在 Python 网络爬虫中自动解决 reCAPTCHA 和 Cloudflare Turnstile？

最有效的方法是使用像 Botasaurus 这样的强大浏览器自动化框架，它处理反检测，同时集成像 CapSolver 这样的专用验证码解决 API 来程序化获取所需的解决方案令牌。

使用 Botasaurus 进行反检测网络爬虫有哪些优势？

Botasaurus 通过简洁的基于装饰器的 API 简化了浏览器自动化，同时提供了必要的内置隐身功能，以最大限度地降低被目标网站检测和阻止的风险。

使用 CapSolver API 解决 reCAPTCHA v2 和 v3 有什么区别？

虽然两者都需要 websiteURL 和 websiteKey，但解决 reCAPTCHA v3（不可见的基于评分的版本）还需要在发送到 CapSolver API 的任务负载中包含一个 pageAction 参数。

CapSolver 返回验证码令牌后会发生什么？

一旦收到令牌（例如 gRecaptchaResponse 或 token），必须立即使用 JavaScript 执行命令将其注入目标网页的隐藏表单字段中，然后才能成功提交到服务器。

CapSolver 令牌在过期前能维持多久？

CapSolver 提供的 reCAPTCHA 和 Turnstile 验证码令牌的有效期非常短，通常在约 2 分钟 内过期，因此需要立即使用。

合规声明：本博客提供的信息仅供参考。CapSolver 致力于遵守所有适用的法律和法规。严禁以非法、欺诈或滥用活动使用 CapSolver 网络，任何此类行为将受到调查。我们的验证码解决方案在确保 100% 合规的同时，帮助解决公共数据爬取过程中的验证码难题。我们鼓励负责任地使用我们的服务。如需更多信息，请访问我们的服务条款和隐私政策。