修复:cf-turnstile-response 字段为必填的错误

cf-turnstile-response field is required - Fix: The cf-turnstile-response Field Is Required Error

消息 "The cf-turnstile-response field is required" 来自站点自己的表单验证,意思是表单提交到达时没有这个名字的字段,或者该字段为空。修复方法取决于是谁发送了表单。在浏览器里,是 Turnstile 小组件没有产生 token。在你自己的脚本里,是没有人去要 token。本指南展示这两种原因,然后用 CapSkip 提供的 token,在 Python 中修复脚本这一种情况。

这条消息是什么意思

它不是 Cloudflare 的错误。像 Laravel 中那样的验证层,会按 "The :attribute field is required" 的模式,用字段名生成这句话,所以消息里的名字就是服务器要找却没找到的名字。这项检查发生在服务器调用 Cloudflare 之前。当服务器确实调用 Cloudflare 的 siteverify 端点 却没有传 response 值时,Cloudflare 会回复它自己的代码 missing-input-response,那是另一条不同的消息。

Cloudflare 的 小组件文档 说,对于放在表单内的小组件,会创建一个名为 cf-turnstile-response 的隐藏 input,它会和其他字段一起提交。所以这个字段只有在小组件运行并产生 token 之后才存在。

字段为什么缺失

原因如何判断修复
小组件从未渲染页面上没有 Turnstile 框,并且浏览器的网络标签页里小组件脚本的请求被拦截允许这个脚本,并从 Cloudflare 给出的准确 URL 加载它,因为 Cloudflare 说经过代理或缓存的副本会在更新时失效
小组件在表单之外框能显示,但隐藏 input 不在 form 元素内部把小组件移到表单里,或者自己把 token 复制到一个字段里
表单在小组件完成之前就发送了只有访客立刻提交时才出现这个错误,再试一次就正常了在小组件产生 token 之前禁用提交按钮
字段用了另一个名字消息里写的是另一个字段名,或者页面设置了自定义的响应字段名发送消息里显示的名字。Cloudflare 记录了一个 response-field-name 选项,默认值是 cf-turnstile-response
小组件的响应字段被关闭了框能显示,但表单里没有名为 cf-turnstile-response 的 input,并且页面把 data-response-field 设为 false去掉这项设置,或者从小组件回调中读取 token,自己放进一个字段里
由脚本提交表单没有浏览器参与,提交里只有你自己的字段获取一个 token 并发送,这就是本指南的其余部分

最后一行是你能用代码修复的,而消息在字段名上帮了你:它打印出服务器想要的名字,所以请原样复制。"如何判断" 这一列是我对小组件行为的解读。Cloudflare 记录了隐藏 input、response-field 和 response-field-name 选项,以及关于脚本 URL 的规则。

你需要什么

  • 一台运行着 CapSkip 的 Windows PC。 Cloudflare Turnstile 识别工具 页面列出了小组件的请求:一个 sitekey 和页面地址。
  • Python 3.10 或更新版本,这是 capskip 1.7.0 声明的最低版本,另外还需要 requests。第一个代码块的第一行给出了同时安装两者的 pip 命令。我在 Python 3.11.7、3.13.7 和 3.14.0 上,使用 capskip 1.7.0 和 requests 2.34.2 运行了这些代码块。
  • 一个你被允许提交的表单。示例使用占位地址 https://example.com/contact,这个表单有一个名为 _token 的隐藏 CSRF 字段、一个 email 字段和一个 message 字段。
  • 对于另一台机器上的脚本,请把 CapSkip 切换到 Server mode,并把那台 PC 的地址作为 host 传入。设置指南在 连接设置中介绍了这个切换。启动 Server mode 会让 CapSkip 接受来自任何地址的连接。要把端口留给你信任的机器,请为其余地址添加一条 Windows Firewall 阻止规则。

我针对我自己写的两个模拟服务器运行了所有内容:一个扮演 CapSkip,一个扮演表单站点。模拟站点会拒绝缺少该字段的表单提交,并打印出本文中的那条消息。它上面的每条规则都是我定的,而且我没有向真正的 CapSkip 应用发送任何任务,所以这里的一切都不能说明真实站点会接受一个 token。

第 1 步:创建会话

把第一个代码块保存为 turnstile_form.py。它后面的两个代码块放在同一个文件的末尾。名为 read_input 的辅助函数读取一个隐藏 input,send_form 则提交你的字段。它把 Referer 头设为表单页面,就像浏览器那样,因为 requests 自己不会发送。

# python -m pip install capskip requests
import re

import requests
from capskip import CapSkip

FORM_URL = "https://example.com/contact"  # the page that shows the form

# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)


def read_input(html, name):
    tag = re.search(r'<input[^>]*name="' + re.escape(name) + r'"[^>]*>', html)
    value = re.search(r'value="([^"]*)"', tag.group(0)) if tag else None
    return value.group(1) if value else None


def open_form():
    session = requests.Session()  # keeps the session cookie
    return session, session.get(FORM_URL, timeout=30).text


def send_form(session, html, extra):
    fields = {"_token": read_input(html, "_token"), "email": "[email protected]", "message": "Hello"}
    fields.update(extra)
    return session.post(FORM_URL, data=fields, headers={"Referer": FORM_URL}, timeout=30)

第 2 步:复现错误

像脚本通常第一次那样提交表单,只带你自己的字段,别的什么都不带。接着添加这个代码块。针对我的模拟服务器,回复是状态码 200,页面再次显示,错误列表里有那条消息。你的站点可能会重定向或返回 422,所以请在响应体里找这句话。

session, html = open_form()
reply = send_form(session, html, {})  # no cf-turnstile-response at all
print(reply.status_code, re.findall(r"<li>(.*?)</li>", reply.text))
# 200 ['The cf-turnstile-response field is required.']

第 3 步:用 CapSkip 的 token 修复

从小组件的 data-sitekey 属性读取 sitekey,用识别工具的 turnstile 方法向 CapSkip 要一个 token,并把结果的 code 值以准确的字段名发送出去。CapSkip API 文档说,识别工具对 Turnstile 使用特定的浏览器 User-Agent,你必须随 token 发送同一个 User-Agent,而答案里包含了它。代码块在它存在时会把它复制到会话上。我的模拟服务器返回了一个,而我没有见过真正的应用对一个小组件会返回什么。

token 只能使用一次。Cloudflare 说每个 token 的有效期是 300 秒,且只供单次使用,所以请在表单提交之前才请求它,而不要放在一个很长的脚本开头。如果 sitekey 不在 data-sitekey 属性里,因为页面调用的是 render 函数,请从那次调用里复制一次。

session, html = open_form()
sitekey = re.search(r'data-sitekey="([^"]+)"', html).group(1)

result = solver.turnstile(sitekey, FORM_URL)
if result.get("userAgent"):  # the docs say the answer names the browser to present
    session.headers["User-Agent"] = result["userAgent"]

reply = send_form(session, html, {"cf-turnstile-response": result["code"]})
print(reply.status_code, re.findall(r"<p>(.*?)</p>", reply.text))
# 200 ['Message sent. Thank you.']  (your site's success text will differ)

针对模拟服务器,三个 Python 版本给出了这些结果:

模拟设置发生了什么
第 2 步,没有发送字段消息出现了,CapSkip 模拟服务器没有收到任务
第 3 步,token 以正确的名字发送一个任务,表单提交被接受
站点期望另一个字段名消息指出了那个字段,把 token 放在它下面发送后被接受
token 第二次发送出现另一条消息 "The captcha could not be verified",所以字段存在,但 token 已被用掉
字段以空值发送同样的 required 消息,所以空字段也算缺失
模拟服务器设为检查 User-Agent没有复制返回的 User-Agent 就发送 token 会被拒绝,复制之后则被接受
同一个 token,没有 Referer 头模拟服务器返回 403,它自己的规则是要求同源的 Referer

请把这张表当作对我的模拟服务器的测试。消息措辞、单次使用和 Referer 规则都是我定的,真实站点会自己决定。

如果加上 token 之后消息仍然存在

  • 另一条消息,例如关于验证失败的消息,表示字段已经到达。请查看 token:是否用了两次、是否超过五分钟,或者是否是为另一个页面地址请求的。

常见问题

cf-turnstile-response required 错误是 Cloudflare 的错误吗?

不是。它是站点的验证在报告缺少一个表单字段。只有当站点把 token 发送到它的验证端点时,Cloudflare 才会介入。

这适用于 Cloudflare 挑战页面吗?

不适用。整页挑战不是表单字段。CapSkip 用 cookie 来应答它, API 文档 对该方法有单独的说明。PHP 和 Node.js 指南展示了 Turnstile 挑战页面需要的两个额外值。它们的发送方式见 用 PHP 识别 Turnstile 。Node.js 版本见 用 Node.js 识别 Turnstile.

脚本可以在和 CapSkip 不同的机器上运行吗?

可以,通过 Server mode。把 CapSkip 所在 PC 的地址作为 host 传入。设置指南说,对服务器部署而言,静态公网 IP 能提供最稳定的远程访问,并且 Server mode 需要 CapSkip 以管理员身份运行。你的识别工具仍然运行在你自己的 Windows 硬件上,没有按次计费。

简短版结论

这个错误意味着服务器没有看到 cf-turnstile-response 值。在浏览器里,要让小组件渲染出来。在脚本里,在表单提交之前才去要 token,并以消息里显示的名字发送。因为 CapSkip 是一个 本地验证码识别工具 ,运行在你自己的 PC 上,所以在已授权的副本上,每次重试都不会产生额外费用。 Python 验证码识别页面 列出了其他 SDK 调用, API 文档 给出了原始请求。