5529 字
28 分钟
Turnstile:给表单加无感人机验证

上一篇聊了域名转入 Cloudflare 的省钱门道,省钱之外,Cloudflare 还有一件更实用的免费武器没动过:Turnstile。这一篇把它接进你自己的网站——从控制台建站点、拿密钥,到前端嵌组件、后端调 siteverify 校验,一条龙走完,最后再把接入时最容易踩的几个坑逐个拆掉。

先说清楚它解决什么问题。只要你的网站有一个能提交东西的入口——注册、登录、留言、评论、找回密码、领券、调接口——机器人就会找上门。它们不是来参观的,是来批量干活的:

  • 注册机:一夜之间给你灌几万个僵尸账号,数据库里全是垃圾,后续清理比接入验证麻烦十倍;
  • 撞库与爆破:拿着泄露的账号密码库往你的登录口上撞,或者对着弱口令一个个试;
  • 灌水与刷量:留言区、评论区被广告和垃圾链接淹没,人工审核根本审不过来;
  • 薅接口:短信验证码接口、优惠券接口、免费额度接口,被脚本当成免费资源往死里薅,薅走的都是真金白银。

这些流量的共同点是:量大、重复、不创造任何价值,还实打实地消耗你的服务器资源和第三方接口费用。人机验证就是在提交入口加一道判断题:你到底是人,还是脚本?

传统验证码为什么惹人烦#

最早的办法是扭曲字符图片,让用户把图里的字母敲出来。机器人 OCR 水平水涨船高,字符就扭得越来越离谱,最后变成了人看不清、机器反而看得清的笑话。

后来流行的是行为勾选加图片挑战:先勾一个「我不是机器人」,运气不好就开始选图——「请选出所有包含红绿灯的图片」「请选出所有公交车」。一格选错,推倒重来。跨海象、消防栓、自行车这类题对不熟悉当地街景的用户尤其不友好,选到第三轮还在怀疑人生。

体验差只是表面问题,更深一层的是代价:

问题具体表现
用户流失每多一道图片挑战,注册和下单的完成率就掉一截,移动端掉得更狠
无障碍缺失视障用户靠读屏根本没法完成图片题,直接被挡在门外
隐私代价主流验证码靠在全网埋点收集行为数据来判断风险,你的用户数据成了它的养料
对抗军备竞赛打码平台几分钱一张图人工代答,验证强度被迫越加越高,真人越来越难过

验证的理想状态是:真人无感通过,机器人过不去,而不是把所有人拉去做题。Turnstile 就是奔着这个目标设计的。

Turnstile 的不同之处#

Turnstile 是 Cloudflare 推出的人机验证服务,2022 年发布,后来转为正式免费提供。它的工作方式和传统验证码完全不同:

  • 多数真人无感通过:小部件在页面上运行时,会在浏览器里跑一系列非交互式的检测——浏览器环境特征、行为信号、硬件与网络侧的若干挑战(比如工作量证明类的小计算),综合判断这次访问像不像真人。判断通过,直接发令牌,用户最多看到一个转瞬即逝的勾,全程不用点任何图片。
  • 不靠出题:没有选红绿灯,没有拼图滑块。只有当信号明显可疑时,托管模式下才可能弹出一个需要点一下的复选框,连这一步都远比图片题轻。
  • 不拿用户数据做广告追踪:Cloudflare 对 Turnstile 的定位说得很明确——它不为了广告目的收集和留存访客数据,这也是很多站点从 reCAPTCHA 迁移过来的直接原因。
  • 免费且不限量:Turnstile 本身免费,调用量没有像样的门槛,对个人站点和小项目非常友好。具体配额与条款以官方文档为准。

当然,它不是银弹。Turnstile 挡的是自动化脚本和低成本批量行为,挡不住真人肉身操作的水军,也挡不住专门针对它做逆向的高成本攻击。但把门槛从「零」抬到「要专门花钱花时间绕过」,就已经能过滤掉绝大多数 opportunistic 的垃圾流量了。

WARNING

人机验证只是入口防线的一层,不能替代后端的限流、风控和业务校验。登录口该有的失败次数限制照样要有,接口该有的权限检查一点都不能省。

准备工作:建站点,拿两把钥匙#

接入 Turnstile 不用写一行代码就能开始,全部在 Cloudflare 控制台完成:

  1. 登录 Cloudflare 控制台,左侧进入 Turnstile 页面;
  2. 点 Add widget(添加小部件),填一个好认的名字,比如站点名加用途,如 blog-login;
  3. 在 Hostname management(域名清单)里填入要使用验证的域名,支持添加多个,子域名按需逐个加;
  4. 选择小部件模式(下一节细讲,先选默认的 Managed 即可);
  5. 创建完成后,控制台会给出两把钥匙:Site Key(站点密钥)和 Secret Key(秘密密钥)。

一个域名可以建多个小部件,建议一个用途一个:登录一个、注册一个、留言一个。这样将来某个入口要单独换模式、看统计、轮换密钥时互不牵连。

两把钥匙的性质完全不同,这是整个接入里最重要的安全常识:

钥匙出现位置公开性作用
Site Key前端页面 HTML / JavaScript 里可以公开,本来就是给浏览器看的标识「这是哪个站点的验证」,用来渲染小部件
Secret Key只存在于你的后端服务器绝对不能出现在前端、不能写进代码仓库、不能打进日志后端向 Cloudflare 校验令牌真伪时证明身份

Secret Key 一旦泄露,任何人都能拿它调用校验接口,你的验证等于被人握住了后门钥匙。正确做法是把它放在服务器的环境变量或密钥管理里,和数据库密码同级对待。真泄露了也别慌,控制台里可以重新生成(roll),换掉之后旧的立刻失效。

三种小部件模式怎么选#

创建小部件时要选模式,这是 Turnstile 和老式验证码在体验上拉开差距的关键设置:

模式用户看到什么何时可能交互适合场景
Managed(托管)一个带 Cloudflare 标识的小部件框Cloudflare 判断风险高时,框里出现需要勾选的复选框;低风险直接打勾通过绝大多数表单,官方推荐的默认选择
Non-interactive(非交互)一个小部件框,全程只展示状态永不要求用户操作,验证不过就直接失败不希望任何交互打断流程、且能接受少量误杀的场景
Invisible(隐形)什么都看不到,没有任何可见元素永不要求用户操作,在后台默默执行对页面美观和流程完整性要求极高的关键转化页

选型的经验法则:

  • 拿不准就用 Managed。它在「通过率」和「拦截率」之间自动权衡,低风险用户无感、高风险用户多点一下,是绝大多数站点的最优解。
  • Non-interactive 适合内部或低风险入口,比如站内搜索、订阅邮箱提交。它绝不打扰用户,代价是判定更保守,个别环境特殊的真人可能直接失败,要有兜底提示。
  • Invisible 适合注册、下单这类寸土寸金的转化页,页面上干干净净,但因为完全没有可见元素,排查问题和向用户解释「为什么提交失败」会更麻烦一些。

三种模式的后端校验流程完全一致,切换模式只是改小部件设置或前端渲染参数,不影响后端代码。

前端接入:把小部件嵌进表单#

前端要做两件事:引入官方脚本,再在表单里放一个小部件容器。

官方脚本的地址是现行固定口径:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

注意脚本域名是 challenges.cloudflare.com,如果你的站点配了严格的 CSP(Content Security Policy),需要把这个域名加进 script-src 和 frame-src 的白名单,否则小部件会被浏览器拦下来,后面排障一节还会提到。

最简的隐式渲染写法,是在表单里加一个带 cf-turnstile 类名的容器,把 Site Key 写进 data-sitekey:

<form action="/login" method="POST">
<input type="text" name="username" placeholder="用户名" />
<input type="password" name="password" placeholder="密码" />
<!-- Turnstile 小部件容器 -->
<div class="cf-turnstile" data-sitekey="你的SiteKey"></div>
<button type="submit">登录</button>
</form>

脚本加载后会自动扫描这类容器并渲染小部件。验证通过时,小部件会在表单里悄悄塞入一个隐藏字段,字段名是固定的:

cf-turnstile-response

用户点提交时,这个字段的值——也就是令牌(token)——会随着表单其他字段一起发到你的后端。后端什么都不用猜,取这个字段就行。

几个必须知道的令牌性质:

  • 有效期约 5 分钟(300 秒):令牌生成后要尽快随表单提交,用户在页面上磨蹭太久,令牌过期,校验必然失败;
  • 只能使用一次:同一个令牌拿去校验第二次,会返回已使用过的错误。这意味着表单校验失败让用户「改个字段重新提交」时,必须刷新令牌,不能复用旧的;
  • 令牌长度上限 2048 字符:后端接收字段时别给它设太短的长度限制。

如果表单是单页应用里动态出现的(比如点按钮才弹出的登录框),隐式渲染扫不到后出现的新容器,这时用显式渲染:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" async defer></script>
// 在容器元素出现之后手动渲染
const widgetId = turnstile.render('#turnstile-box', {
sitekey: '你的SiteKey',
callback: function (token) {
// 验证通过,token 就在这里,也可以等提交时从隐藏字段取
console.log('验证通过');
},
'expired-callback': function () {
// 令牌过期时触发,提示用户或自动重置
turnstile.reset(widgetId);
},
'error-callback': function () {
// 小部件本身出错时触发
console.log('验证组件加载失败');
},
});

常用回调有三个:callback 是通过时触发,expired-callback 是令牌过期时触发,error-callback 是组件出错时触发。提交失败需要让用户重试时,调用 turnstile.reset(widgetId) 把小部件重置、生成新令牌,这是处理「令牌只能用一次」最稳妥的姿势。

小部件还支持一批 data- 配置,隐式渲染时直接写在容器上:

属性作用常用取值
data-sitekeySite Key,必填控制台给的那串
data-theme外观主题auto / light / dark
data-size尺寸normal / compact
data-action自定义动作标签,校验结果里会带回如 login、register,便于后端区分来源
data-cdata自定义数据,校验结果里原样带回业务侧的关联 ID 等

深色主题的站点记得把 data-theme 设成 dark 或 auto,不然白色小部件框在深色页面上会非常扎眼。

后端校验:siteverify 这一关不能省#

前端小部件只是「出题和收卷」,真正的判卷在后端。只嵌前端、不做后端校验,等于装了道没有锁的门——机器人完全可以跳过浏览器,直接构造请求打你的接口,连小部件都不用看。

校验端点是现行固定口径:

POST https://challenges.cloudflare.com/turnstile/v0/siteverify

请求体带三个参数,后端拿到表单后立刻调用:

参数必填说明
secret是你的 Secret Key,只在后端出现
response是表单里 cf-turnstile-response 字段的值
remoteip否,但强烈建议带提交者的真实 IP,能显著提升判定准确性

以 Node.js 为例,用表单编码提交:

async function verifyTurnstile(token, ip) {
const formData = new URLSearchParams();
formData.append('secret', process.env.TURNSTILE_SECRET_KEY);
formData.append('response', token);
if (ip) formData.append('remoteip', ip);
const res = await fetch(
'https://challenges.cloudflare.com/turnstile/v0/siteverify',
{ method: 'POST', body: formData }
);
const data = await res.json();
return data;
}

返回的 JSON 长这样,核心就看 success:

{
"success": true,
"challenge_ts": "2026-11-15T01:23:45.678Z",
"hostname": "example.com",
"error-codes": [],
"action": "login",
"cdata": ""
}

各字段的含义:

  • success:校验是否通过,true 才放行,这是唯一的放行依据;
  • challenge_ts:这次验证完成的时间戳;
  • hostname:令牌是在哪个域名上生成的,建议后端核对它等于你预期的域名,防止有人拿别的站点(甚至他自己站点)的令牌来你这儿复用;
  • action / cdata:前端设置了 data-action / data-cdata 时原样带回,可用来核对「这个令牌确实是登录表单发的,不是留言表单发的」;
  • error-codes:失败时给出的原因码,排障全靠它。

常见错误码对照:

错误码含义
missing-input-secret没传 secret 参数
invalid-input-secretsecret 不对,最常见是把 Site Key 当 Secret Key 用了
missing-input-response没传令牌
invalid-input-response令牌无效、格式不对或已过期
timeout-or-duplicate令牌超时,或已经被校验过一次(重复提交)
bad-request请求本身格式错误
internal-errorCloudflare 侧内部错误,可重试

校验环节有两条纪律:

第一,success 不为 true,就坚决拒绝这次提交,没有例外通道。不要写「校验没过但看起来像正常用户就先放行」这种代码,机器人第一个找到的就是这种后门。

第二,要想清楚校验请求本身失败时怎么办。如果你的服务器到 Cloudflare 的网络断了、siteverify 超时了,这时候是拒绝所有提交(fail-closed,安全优先,可能误伤全部真人),还是先放行并记录日志(fail-open,可用性优先,短暂失去防护)?没有标准答案:登录、支付类入口建议 fail-closed 并给用户明确报错;留言、订阅这类低风险入口可以 fail-open 加事后风控。这个权衡必须在写代码时主动做,而不是等出事了才发现默认行为不是你想要的。

一个完整小例子:留言表单全闭环#

把前后端拼起来,一个最小可用的留言板是这样的。前端:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>留言板</title>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
<form id="comment-form" action="/api/comments" method="POST">
<input type="text" name="nickname" placeholder="昵称" required />
<textarea name="content" placeholder="说点什么…" required></textarea>
<div class="cf-turnstile"
data-sitekey="你的SiteKey"
data-action="comment"
data-theme="auto"></div>
<button type="submit">提交留言</button>
</form>
</body>
</html>

后端(Node.js + Express,逻辑部分抽出来,任何语言都是同样的三步):

app.post('/api/comments', async (req, res) => {
const token = req.body['cf-turnstile-response'];
const ip = req.ip;
// 第一步:令牌字段根本不存在,直接拒绝
if (!token) {
return res.status(400).json({ ok: false, msg: '缺少人机验证信息' });
}
// 第二步:调 siteverify 校验
let verify;
try {
const formData = new URLSearchParams();
formData.append('secret', process.env.TURNSTILE_SECRET_KEY);
formData.append('response', token);
if (ip) formData.append('remoteip', ip);
const resp = await fetch(
'https://challenges.cloudflare.com/turnstile/v0/siteverify',
{ method: 'POST', body: formData }
);
verify = await resp.json();
} catch (e) {
// 校验服务不可达:低风险留言入口选择放行并记录,登录类入口应改为拒绝
console.error('Turnstile 校验请求失败', e);
verify = { success: true, degraded: true };
}
// 第三步:校验不过或域名对不上,拒绝提交
if (!verify.success || verify.hostname !== 'example.com') {
return res.status(403).json({ ok: false, msg: '人机验证未通过,请刷新页面重试' });
}
// 校验通过,才真正处理业务
const { nickname, content } = req.body;
await saveComment({ nickname, content, ip });
return res.json({ ok: true, msg: '留言已提交' });
});

这个闭环里把前面讲的点都用上了:令牌从固定字段取、secret 从环境变量读、带上 remoteip、核对 hostname、校验不过坚决拒绝、校验服务异常时按业务风险做了明确策略。换成 PHP、Python、Go 也只是换个发 HTTP 请求的写法,参数和判断逻辑一字不用改。

测试密钥:本地调试别拿生产钥匙硬扛#

开发阶段有个高频痛点:本地用 localhost 调试,域名不在小部件的域名清单里,小部件压根不渲染。Cloudflare 官方提供了一整套测试专用密钥解决这个问题,它们的行为是写死的、完全可预测:

密钥用途行为
测试 Site Key(以 1x0000 开头那把)前端渲染永远显示为验证通过
测试 Site Key(以 2x0000 开头那把)前端渲染永远显示为验证失败
测试 Site Key(以 3x0000 开头那把)前端渲染永远强制弹出交互质询
测试 Secret Key(以 1x0000 开头那把)后端校验siteverify 永远返回 success: true
测试 Secret Key(以 2x0000 开头那把)后端校验siteverify 永远返回 success: false
测试 Secret Key(以 3x0000 开头那把)后端校验永远返回 timeout-or-duplicate 错误

具体的完整密钥字符串以官方文档为准,写代码时从文档里复制,别凭记忆手敲。用测试密钥时,令牌字段的值是固定的 XXXX.DUMMY.TOKEN.XXXX,不依赖真实的 Cloudflare 交互,断网环境都能调通前后端逻辑。

使用纪律就一条:测试密钥只能出现在本地和测试环境,绝不能带上生产。生产环境如果误用了「永远通过」的测试 Secret Key,你的验证就是敞开的摆设,而且从界面上完全看不出来——用户能正常提交、日志里全是 success,直到垃圾流量灌进来才发现。上线检查清单里务必加一项:确认环境变量里是生产密钥。

另外,正式密钥也可以在本地用:把 localhost 加进小部件的域名清单即可(官方明确支持 localhost 调试)。两种方式任选其一,测试密钥胜在能稳定复现失败、超时等各种边界情况,写自动化测试时尤其顺手。

排障:接入最常见的几个坑#

小部件不显示,一片空白#

按这个顺序查:

  1. 域名没加进清单:打开页面域名和小部件 Hostname 清单逐字对照,www.example.com 和 example.com 是两个条目,别想当然;本地调试则确认清单里有 localhost 或改用测试 Site Key。
  2. 脚本被拦截:浏览器控制台看有没有 challenges.cloudflare.com 的请求报错;站点有 CSP 就把该域名加进 script-src 与 frame-src;某些广告拦截插件也会误伤验证脚本,可以无痕窗口复测排除。
  3. 脚本加载方式冲突:用了显式渲染参数 ?render=explicit 却没调 turnstile.render(),小部件永远不会出现;反过来,隐式渲染时容器要在脚本执行前存在于 DOM 中。
  4. Site Key 写错:多一位少一位都会渲染失败,控制台通常有明确报错,从控制台重新复制一遍。

用户反馈一直验证失败或转圈#

  • 令牌过期:用户打开页面挂了十分钟才提交,令牌早过了 5 分钟有效期。解法是监听 expired-callback 自动 reset 刷新,或在点提交前检查并刷新。
  • 令牌被重复提交:表单校验失败后原地重提、或者前端做了自动重试,第二次提交带着已用过的令牌,返回 timeout-or-duplicate。每次提交失败都要重置小部件拿新令牌。
  • 系统时钟不准:用户设备时间偏差过大可能影响验证过程,报错话术里可以提示检查系统时间,这是小概率但真实存在的原因。
  • 网络环境特殊:极少数网络下到 Cloudflare 挑战域名的连通性有问题,真人会卡住。给失败提示留一个「重试」入口,实在过不去的用户要有人工兜底通道。

后端校验总是返回 invalid#

  • 两把钥匙用混了:最高频的错误,没有之一。invalid-input-secret 基本就是 secret 传错——把 Site Key 填进了 secret,或者把 A 小部件的 Secret 用到了 B 小部件的令牌上。密钥是按小部件成对的,逐个核对。
  • 令牌字段取错:后端取的字段名不是 cf-turnstile-response,或者前端表单根本没把隐藏字段带上(比如用 JavaScript 手动拼请求体时漏了它)。
  • 重复校验:同一个请求被中间件和业务代码各校验了一次,第二次必然 timeout-or-duplicate。全站只保留一个校验入口。
  • secret 里混入空格或引号:环境变量从控制台复制时带了首尾空白,在配置里肉眼很难看出来,打印长度或做一次 trim 就能定位。
WARNING

排障时最有效的动作是把 siteverify 的完整返回 JSON 打进日志(error-codes 尤其要留),九成问题看错误码就能定位。唯独注意:日志里可以记令牌的前几位用于关联,但不要记 Secret Key 本身。

小结#

  • Turnstile 的核心价值是让验证对真人隐形、对机器人收费:不用做题、不用交隐私数据、服务本身免费;
  • 接入是前后端两半活:前端引入 api.js 并渲染小部件拿到令牌,后端调 siteverify 校验,缺了后端校验等于没接;
  • 两把钥匙分工明确:Site Key 放前端随便看,Secret Key 只进后端环境变量,泄露就立刻重新生成;
  • 模式选择默认 Managed,转化关键页可用 Invisible,只求零打扰可用 Non-interactive;
  • 令牌的两个脾气要记牢:约 5 分钟过期、只能用一次,重试流程必须设计成自动刷新令牌;
  • 测试密钥是本地调试和自动化测试的好帮手,但上线前必须确认生产环境用的是真密钥。

下一篇进入 Cloudflare Registrar:把域名转进来,按批发价续费,能省则省。

Turnstile:给表单加无感人机验证
https://www.anexns.cloudns.org/posts/cloudflare-turnstile/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0