SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场cloudflare-turnstile

cloudflare-turnstile

安全与审计

查看项目

更新于 10-15 11:56

技能介绍

用途

Cloudflare Turnstile 是一种替代 CAPTCHA 的机器人防护方案，用于保护表单、登录/注册流程、防止垃圾提交，以及从 reCAPTCHA 迁移等场景。该技能（skill）提供从创建组件到服务端校验的完整集成指导。

主要能力

  • 前端组件嵌入：支持隐式渲染（页面加载自动渲染）与显式渲染（SPA 程序化控制），并提供 React 集成方式（@marsidev/react-turnstile）。
  • 服务端校验：通过 Siteverify API 进行强制服务端验证，示例覆盖 Cloudflare Workers 与 Hono 框架。
  • 常见模式：提供 Hono + Cloudflare Workers、React + Next.js App Router 的完整代码示例。
  • 测试支持：提供虚拟 sitekey 与 secret key（始终通过、始终拦截、强制交互、令牌已使用等）。
  • 资源与排查：包含 CSP 检查脚本、组件配置参考、错误码排查（100*/200*/300*/400*/600*）、测试指南、React 集成参考，以及 Hono、React、隐式/显式渲染与校验的完整模板。
  • 高级特性：预清除（Pre-Clearance，为 SPA 发放跨页面导航持久化的 cookie）、自定义 action 与数据（最多 255 字符）。

使用方式

  1. 在 Cloudflare 控制台创建组件，复制 sitekey（公开）与 secret key（私密）。
  2. 前端引入脚本 https://challenges.cloudflare.com/turnstile/v0/api.js 并放置组件容器。
  3. 服务端接收 cf-turnstile-response 令牌，向 https://challenges.cloudflare.com/turnstile/v0/siteverify 发起 POST 请求校验，并附带 secret、response 与 remoteip（客户端 IP）。
  4. 根据返回的 success 字段决定是否放行。

关键规则

必须遵守：始终调用 Siteverify API 进行服务端校验；使用 HTTPS；保护 secret key 不暴露于前端；处理令牌过期（5 分钟）；实现错误回调；测试时使用虚拟密钥；设置合理超时；在指定时校验 action/hostname；定期轮换密钥；监控分析数据；始终向 Siteverify 传递客户端 IP（Workers 使用 CF-Connecting-IP，Node.js 使用 X-Forwarded-For）。

禁止事项：跳过服务端校验；代理 api.js 脚本（必须从 Cloudflare CDN 加载）；复用令牌（每个令牌仅可使用一次）；使用 GET 请求（Siteverify 仅接受 POST）；暴露 secret key；信任客户端校验；缓存 api.js；在测试中使用生产密钥；忽略错误回调。

适用场景

  • 保护网站表单、登录与注册页面
  • 防止垃圾提交与自动化滥用
  • 从 reCAPTCHA 迁移
  • 在 Cloudflare Workers、Hono、React、Next.js 等技术栈中集成机器人防护

限制与已知问题

该技能整理了 15 个已知问题及预防方法，包括：缺少服务端校验、令牌 5 分钟过期、secret key 前端暴露、对 Siteverify 使用 GET 请求、CSP 阻止 iframe（错误 200500）、组件崩溃（错误 300030）、配置错误（错误 600010）、Safari 18 / macOS 15 的“隐藏 IP”问题（错误 300010）、Brave 浏览器彩带动画失败、Next.js + Jest 不兼容、localhost 未加入允许列表（错误 110200）、令牌复用、Chrome/Edge 首次加载失败（错误 106010）、多组件视觉状态卡住、Jest 与 @marsidev/react-turnstile 的兼容性问题（建议迁移至 Vitest）。

其他限制：令牌 5 分钟过期且单次使用，校验后（无论成功或失败）即被消耗，需调用 turnstile.reset() 生成新令牌；Siteverify 仅接受 POST；api.js 不得代理或缓存；开发/预发布/生产应使用不同组件。

配置要点

wrangler.jsonc 中通过 vars 配置 TURNSTILE_SITE_KEY，通过 secrets 配置 TURNSTILE_SECRET_KEY（使用 wrangler secret put 命令）。CSP 需允许 script-src 与 frame-src 指向 https://challenges.cloudflare.com。

版本与状态

状态：生产就绪。最后更新：2026-01-21。依赖：无（React 可选 @marsidev/react-turnstile）。最新版本：@marsidev/react-turnstile@1.4.1、turnstile-types@1.2.3。2025 年更新包括：12 月修复脚本加载竞态条件；8 月新增 rerenderOnCallbackChange 属性；3 月升级分析功能（TopN 统计、异常检测）；1 月短暂强制 remoteip 校验；WCAG 2.1 AA 合规，免费计划（20 个组件、7 天分析），企业版功能（无限组件、临时 ID、任意主机名、30 天分析、offlabel 品牌）。