在自有 QA 中使用 CaptchaAI 管理 user-agent

安全范围： 本指南仅适用于你自有或经授权的 QA、staging 与预发布环境，覆盖针对你自己 CAPTCHA 集成的诊断、测试与可观测性模式 — 不涉及第三方站点或未授权流程。

同一条用例昨天跑通、今天却卡在验证码环节 —— 代码没动，变的往往是 user-agent。把 UA 当成用例的一部分固定下来：浏览器、HTTP 客户端和提交给 CaptchaAI 的请求用同一个 UA，用例才可复现。

为什么 user-agent 会影响测试结果

UA 不是要调优的参数，而是要锁定的变量。

维护一份受控的 UA 清单

清单越短越好，覆盖你承诺支持的浏览器组合即可。版本号、平台标识和随 UA 发出的请求头都要来自真实浏览器；拼凑的 UA 会让结果失去参考价值。

把 UA 与用例编号绑定

每条用例固定一个 UA，映射关系随用例进版本库。拿到失败的 case 就能还原当时的浏览器画像，不用靠猜。

国内团队的 staging 常同时挂两套验证码：面向海外的 reCAPTCHA 或 Turnstile，面向国内的 GeeTest（极验）滑块。reCAPTCHA 依赖 Google 托管脚本，国内网络下加载本就不稳定；UA 再随机变化，就分不清失败来自网络还是集成。两条链路各绑一组固定 UA，原因才能区分。（CaptchaAI 支持 GeeTest v3 与 Turnstile，GeeTest v4 为即将支持。）

在 CaptchaAI 请求中保持同一个 UA

提交识别任务时，把浏览器实际使用的 UA 一并传过去：浏览器用什么，API 请求就带什么。在 CI 里 API Key 从 vault 注入，UA 从用例配置读取；每次运行记录耗时、状态码与所用 UA。

示例 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()

故障排除

常见问题

UA 清单多久更新一次？

跟着浏览器大版本走，每 1—2 个月一次。标准不是新旧，而是版本是否还对应你支持的范围。

一次会话里可以换 UA 吗？

不建议。会话内保持同一个 UA 是可复现的前提。要覆盖多种画像，就跑多条用例，每条固定一个 UA。

UA 需要和其他请求头一起对齐吗？

需要。请求头与 UA 属于同一套画像，只改 UA 会得到不存在的组合。

这套流程会接触生产流量吗？

不会。示例都假设你自有的 QA 域名。数据采集场景另需遵守网络安全法、数据安全法与 PIPL。

安全相关指南

• CaptchaAI 快速入门
• 授权范围内的 QA 测试
• 自有表单的接口测试
• 浏览器失败但 API 通过时的排查
• 用 API 识别 reCAPTCHA v2
• 用 API 识别 Cloudflare Turnstile
• 用 API 识别 GeeTest v3

用 CaptchaAI 在自有环境中验证 CAPTCHA 集成。