如何使用Botasaurus和CapSolver在Python中解决CAPTCHA（完整指南）
Ethan Collins
Pattern Recognition Specialist
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 分钟 内过期，因此需要立即使用。
