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

消息 "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 文档 给出了原始请求。
