staging 里的 reCAPTCHA 组件明明加载出来了，后端却把 token 判定为无效——肉眼盯页面很难定位。打开 Chrome DevTools Protocol（CDP）的 Network 面板，几分钟就能看清是网络超时、sitekey 配错，还是 backend 校验的问题。CDP 直接暴露请求生命周期，不用套 WebDriver，是自有 QA 环境排查 CAPTCHA 集成问题的常用工具。
安全范围： 本指南仅适用于你自有或经授权的 QA、staging 与预发布环境。内容覆盖针对你自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。
诊断范围与边界
这套方法只用在自有或经授权的测试页面：浏览器诊断、网络检查、请求生命周期追踪，定位 sitekey，核对 backend 验证结果。
用 CDP 追踪网络请求
CDP 会话可以直接监听 Network.requestWillBeSent 事件，实时打印每个请求的 URL。下面用 Playwright 打开 CDP session，订阅网络事件，再跳转到自有 QA 页面：
import asyncio
from playwright.async_api import async_playwright
async def trace_qa():
async with async_playwright() as p:
browser = await p.chromium.launch()
ctx = await browser.new_context()
page = await ctx.new_page()
client = await ctx.new_cdp_session(page)
await client.send('Network.enable')
client.on('Network.requestWillBeSent', lambda e: print(e['request']['url']))
await page.goto('https://staging.example.com/captcha-demo')
跑完就能看到 reCAPTCHA、Turnstile 相关请求有没有真正发出——这是判断问题在前端还是网络层的第一步。
在 QA 页面定位 sitekey
打开自有 QA 页面（例如 https://staging.example.com/captcha-demo），从 .g-recaptcha 或 .cf-turnstile 元素读取 data-sitekey，和 backend 配置比对。sitekey 对不上，是“组件渲染了但验证失败”最常见的原因。
向 CaptchaAI 提交诊断任务
确认 sitekey 无误后，把 staging 页面 URL 提交给 in.php，轮询 res.php 直到 status 为 1，并把求解耗时记录成诊断指标，方便和历史基线对比。
核对 backend 验证结果
把 token 注入 QA 表单并提交，用 CDP 观察 backend 返回的状态码。被拒绝时，先核对 action、sitekey、secret 是否和服务器端配置一致。
国内测试环境容易踩的坑
reCAPTCHA 脚本从 Google 域名加载，国内网络可达性不稳定，容易被误判成集成缺陷。
先看
recaptcha/api.js是否超时或非 200：是，就先查网络，别急着改代码；脚本正常加载但 widget 不渲染，才是真正的集成问题。国内站点通常遇到的是 GeeTest（极验），诊断思路类似。
常见故障排查
- 测试脚本找不到 widget：检查 staging 里的选择器和等待时机。
- reCAPTCHA 脚本请求超时：先确认是网络问题还是页面集成问题。
- CaptchaAI 返回
ERROR_NO_SLOT_AVAILABLE：内部 pipeline 按指数退避重试。 - backend QA 拒绝 token：核对
action/sitekey/secret。 - 端到端耗时明显偏高：重新测量，排查内部网络抖动。
让诊断结果可追溯
每次 QA 运行都生成结构化日志，记录 token 耗时、HTTP 响应码、任务编号、队列深度，用 OpenTelemetry 串联 correlation id，方便重放整条链路。
上线前检查清单
- 测试范围严格限定在自有或经授权的资源上。
- CaptchaAI 的 key 放在 CI secret 仓库或 vault 里，不写进源代码。
- 每次运行记录调用耗时和响应状态码。
- 给瞬时错误配置好幂等重试和上限。
- 测试能在 CI 里可复现地反复跑通。
完整 QA 调用示例
下面是在自有 staging 环境里用 CaptchaAI 测试 CAPTCHA widget 的最小流程，可以接到上面的诊断脚本后面：
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL'] # 例如 https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']
def submit_qa_recaptcha() -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': QA_PAGE_URL,
'websiteKey': QA_SITE_KEY,
},
}
response = requests.post(
'https://api.captchaai.com/createTask',
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()['taskId']
def fetch_qa_result(task_id: str) -> dict:
payload = {'clientKey': API_KEY, 'taskId': task_id}
response = requests.post(
'https://api.captchaai.com/getTaskResult',
json=payload,
timeout=30,
)
response.raise_for_status()
return response.json()
常见问题
这套流程会碰到生产流量或真实第三方站点吗？
不会，所有示例都假设 staging.example.com 之类的授权环境，请在自有 staging 副本里复现生产配置。
CDP 检测到了 sitekey，CaptchaAI 却返回 ERROR_NO_SLOT_AVAILABLE？
通常是并发线程用满了，与 sitekey 无关。按指数退避重试，或检查套餐线程数。
API key 能写进代码里吗？
不能。用 CI secret 管理器或 vault 注入；已提交进仓库的 key 要立即轮换。
国内网络下 reCAPTCHA 加载失败，是集成问题吗？
不一定，先看 recaptcha/api.js 是否超时或非 200，是的话大概率是网络问题，不是代码 bug。
相关指南
- CaptchaAI 快速入门
- 授权 CAPTCHA QA 测试
- 自有表单 CAPTCHA endpoint 测试
- 浏览器测试失败但 API 通过的排查
- 用 API 解决 reCAPTCHA v2
- 用 API 解决 Cloudflare Turnstile
- 用 API 解决 GeeTest v3
在自有环境中用 CaptchaAI 验证你的 CAPTCHA 集成。
