上一篇聊了域名转入 Cloudflare 的省钱门道,省钱之外,Cloudflare 还有一件更实用的免费武器没动过:Turnstile。这一篇把它接进你自己的网站——从控制台建站点、拿密钥,到前端嵌组件、后端调 siteverify 校验,一条龙走完,最后再把接入时最容易踩的几个坑逐个拆掉。
先说清楚它解决什么问题。只要你的网站有一个能提交东西的入口——注册、登录、留言、评论、找回密码、领券、调接口——机器人就会找上门。它们不是来参观的,是来批量干活的:
- 注册机:一夜之间给你灌几万个僵尸账号,数据库里全是垃圾,后续清理比接入验证麻烦十倍;
- 撞库与爆破:拿着泄露的账号密码库往你的登录口上撞,或者对着弱口令一个个试;
- 灌水与刷量:留言区、评论区被广告和垃圾链接淹没,人工审核根本审不过来;
- 薅接口:短信验证码接口、优惠券接口、免费额度接口,被脚本当成免费资源往死里薅,薅走的都是真金白银。
这些流量的共同点是:量大、重复、不创造任何价值,还实打实地消耗你的服务器资源和第三方接口费用。人机验证就是在提交入口加一道判断题:你到底是人,还是脚本?
传统验证码为什么惹人烦
最早的办法是扭曲字符图片,让用户把图里的字母敲出来。机器人 OCR 水平水涨船高,字符就扭得越来越离谱,最后变成了人看不清、机器反而看得清的笑话。
后来流行的是行为勾选加图片挑战:先勾一个「我不是机器人」,运气不好就开始选图——「请选出所有包含红绿灯的图片」「请选出所有公交车」。一格选错,推倒重来。跨海象、消防栓、自行车这类题对不熟悉当地街景的用户尤其不友好,选到第三轮还在怀疑人生。
体验差只是表面问题,更深一层的是代价:
| 问题 | 具体表现 |
|---|---|
| 用户流失 | 每多一道图片挑战,注册和下单的完成率就掉一截,移动端掉得更狠 |
| 无障碍缺失 | 视障用户靠读屏根本没法完成图片题,直接被挡在门外 |
| 隐私代价 | 主流验证码靠在全网埋点收集行为数据来判断风险,你的用户数据成了它的养料 |
| 对抗军备竞赛 | 打码平台几分钱一张图人工代答,验证强度被迫越加越高,真人越来越难过 |
验证的理想状态是:真人无感通过,机器人过不去,而不是把所有人拉去做题。Turnstile 就是奔着这个目标设计的。
Turnstile 的不同之处
Turnstile 是 Cloudflare 推出的人机验证服务,2022 年发布,后来转为正式免费提供。它的工作方式和传统验证码完全不同:
- 多数真人无感通过:小部件在页面上运行时,会在浏览器里跑一系列非交互式的检测——浏览器环境特征、行为信号、硬件与网络侧的若干挑战(比如工作量证明类的小计算),综合判断这次访问像不像真人。判断通过,直接发令牌,用户最多看到一个转瞬即逝的勾,全程不用点任何图片。
- 不靠出题:没有选红绿灯,没有拼图滑块。只有当信号明显可疑时,托管模式下才可能弹出一个需要点一下的复选框,连这一步都远比图片题轻。
- 不拿用户数据做广告追踪:Cloudflare 对 Turnstile 的定位说得很明确——它不为了广告目的收集和留存访客数据,这也是很多站点从 reCAPTCHA 迁移过来的直接原因。
- 免费且不限量:Turnstile 本身免费,调用量没有像样的门槛,对个人站点和小项目非常友好。具体配额与条款以官方文档为准。
当然,它不是银弹。Turnstile 挡的是自动化脚本和低成本批量行为,挡不住真人肉身操作的水军,也挡不住专门针对它做逆向的高成本攻击。但把门槛从「零」抬到「要专门花钱花时间绕过」,就已经能过滤掉绝大多数 opportunistic 的垃圾流量了。
WARNING人机验证只是入口防线的一层,不能替代后端的限流、风控和业务校验。登录口该有的失败次数限制照样要有,接口该有的权限检查一点都不能省。
准备工作:建站点,拿两把钥匙
接入 Turnstile 不用写一行代码就能开始,全部在 Cloudflare 控制台完成:
- 登录 Cloudflare 控制台,左侧进入 Turnstile 页面;
- 点 Add widget(添加小部件),填一个好认的名字,比如站点名加用途,如
blog-login; - 在 Hostname management(域名清单)里填入要使用验证的域名,支持添加多个,子域名按需逐个加;
- 选择小部件模式(下一节细讲,先选默认的 Managed 即可);
- 创建完成后,控制台会给出两把钥匙: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-sitekey | Site 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-secret | secret 不对,最常见是把 Site Key 当 Secret Key 用了 |
missing-input-response | 没传令牌 |
invalid-input-response | 令牌无效、格式不对或已过期 |
timeout-or-duplicate | 令牌超时,或已经被校验过一次(重复提交) |
bad-request | 请求本身格式错误 |
internal-error | Cloudflare 侧内部错误,可重试 |
校验环节有两条纪律:
第一,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 调试)。两种方式任选其一,测试密钥胜在能稳定复现失败、超时等各种边界情况,写自动化测试时尤其顺手。
排障:接入最常见的几个坑
小部件不显示,一片空白
按这个顺序查:
- 域名没加进清单:打开页面域名和小部件 Hostname 清单逐字对照,
www.example.com和example.com是两个条目,别想当然;本地调试则确认清单里有localhost或改用测试 Site Key。 - 脚本被拦截:浏览器控制台看有没有
challenges.cloudflare.com的请求报错;站点有 CSP 就把该域名加进script-src与frame-src;某些广告拦截插件也会误伤验证脚本,可以无痕窗口复测排除。 - 脚本加载方式冲突:用了显式渲染参数
?render=explicit却没调turnstile.render(),小部件永远不会出现;反过来,隐式渲染时容器要在脚本执行前存在于 DOM 中。 - 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:把域名转进来,按批发价续费,能省则省。