Cloudflare Turnstile cData/action 传递教程

在处理 Cloudflare Turnstile 表单时，很多接口会把验证结果字段命名为 turnstileToken、cf-turnstile-response、X-Turnstile-Response 或其他业务字段。穿云 API 的处理方式是：目标接口需要 token 的位置填写 [cf_token]，由穿云在请求转发前自动替换为有效的 Turnstile token。

如果目标网页在创建 Turnstile 小部件时还使用了 cData 或 action，则需要在请求头中同时传给穿云：

x-cb-sitekey: <TURNSTILE_SITEKEY>
x-cb-cdata: <CDATA>
x-cb-action: <ACTION>

适用场景

目标站点提交表单时触发 Turnstile，而不是页面首次访问时的 JS 质询。
目标接口需要提交 turnstileToken、cf-turnstile-response 或类似 token 字段。
网页源码或网络请求中能看到 Turnstile 的 sitekey，并且小部件配置里包含 action 或 cData。

第一步：确认 sitekey、cData 和 action

打开浏览器开发者工具，查看 Turnstile 小部件初始化参数。常见形式如下：

turnstile.render('#turnstile-widget', {
  sitekey: '0x4AAAA...',
  action: 'login',
  cData: 'user-cdata'
})

也可能出现在 HTML 属性中：

<div class="cf-turnstile"
     data-sitekey="0x4AAAA..."
     data-action="login"
     data-cdata="user-cdata"></div>

如果网页没有配置 action 或 cData，请求头可以不传对应字段。若目标后端校验了这些值，则必须保持与网页初始化参数一致。

第二步：在穿云请求头中传递参数

使用穿云 V2 时，基础请求头包含 API Key、目标域名、版本、代理和 Turnstile sitekey。需要传递 cData 和 action 时，额外加入 x-cb-cdata 与 x-cb-action：

curl -X POST "https://api.cloudbypass.com/api/login" ^
  -H "x-cb-apikey: YOUR_APIKEY" ^
  -H "x-cb-host: target.com" ^
  -H "x-cb-version: 2" ^
  -H "x-cb-proxy: http://user:pass@proxy-host:port" ^
  -H "x-cb-sitekey: 0x4AAAA..." ^
  -H "x-cb-cdata: user-cdata" ^
  -H "x-cb-action: login" ^
  -H "content-type: application/json" ^
  --data "{"username":"[email protected]","password":"demo-password","turnstileToken":"[cf_token]"}"

这里的重点是：x-cb-cdata 和 x-cb-action 用于生成 Turnstile token；目标接口里的 turnstileToken 字段仍然填写 [cf_token]。

Python 示例

import requests

url = "https://api.cloudbypass.com/api/login"

headers = {
    "x-cb-apikey": "YOUR_APIKEY",
    "x-cb-host": "target.com",
    "x-cb-version": "2",
    "x-cb-proxy": "http://user:pass@proxy-host:port",
    "x-cb-sitekey": "0x4AAAA...",
    "x-cb-cdata": "user-cdata",
    "x-cb-action": "login",
    "content-type": "application/json",
}

payload = {
    "username": "[email protected]",
    "password": "demo-password",
    "turnstileToken": "[cf_token]",
}

resp = requests.post(url, headers=headers, json=payload, timeout=60)
print(resp.status_code, resp.headers.get("x-cb-status"))
print(resp.text)

不同 token 字段怎么填？

字段名由目标网站决定，穿云只负责替换 [cf_token]。常见写法包括：

{ "turnstileToken": "[cf_token]" }
{ "cf-turnstile-response": "[cf_token]" }
{ "accessToken": "[cf_token]" }

如果目标站要求把 token 放在请求头，也同样使用占位符：

X-Turnstile-Response: [cf_token]
Authorization: Bearer [cf_token]

注意事项

x-cb-cdata 对应 Turnstile 的 cData，x-cb-action 对应 Turnstile 的 action。
Cloudflare Turnstile 通常限制 action 最多 32 个字符，cData 最多 255 个字符。
建议只使用字母、数字、下划线和短横线，避免特殊字符导致目标站校验失败。
穿云 V2 需要配置可用代理，Turnstile 场景建议使用固定或粘性代理 IP，避免 token 与会话不一致。
不要把 [cf_token] 提前替换成本地字符串；它必须保留到穿云 API 请求中，由穿云自动替换。

排查建议

如果目标接口提示 token 无效，先确认 token 字段名是否正确，例如目标实际需要 cf-turnstile-response，而不是 turnstileToken。
如果后端校验 action 或 cData，确认 x-cb-action、x-cb-cdata 与网页初始化参数完全一致。
如果返回挑战超时或代理错误，优先检查 x-cb-proxy 的可用性、地区和粘性时长。
如果返回参数错误，检查 x-cb-sitekey 是否填写了 Turnstile sitekey，而不是页面 URL 或其他业务 ID。

小结

当目标接口字段叫 turnstileToken 时，请在该字段中填写 [cf_token]。当目标 Turnstile 小部件还使用 cData 或 action 时，请通过 x-cb-cdata 和 x-cb-action 请求头传递给穿云。两者配合后，穿云会按目标站所需参数生成 token，并在转发请求前完成替换。

穿云API 技术文档