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

cloudflare-turnstile

安全与审计

查看项目

更新于 10-15 13:44

技能介绍

用途

Cloudflare Turnstile 技能用于在网站或应用中实现机器人防护与验证能力，作为 CAPTCHA 的替代方案。根据资料，该技能适用于用户提出“添加 Turnstile”“实现机器人防护”“校验 Turnstile 令牌”“修复 Turnstile 错误”“设置验证码”等需求的场景。

主要能力

  • 指导创建 Turnstile 小部件并获取 sitekey（公开）与 secret key（私有）。
  • 前端集成：通过加载 https://challenges.cloudflare.com/turnstile/v0/api.js 渲染小部件，支持隐式渲染（静态表单）与显式渲染（SPA/动态界面），并提供 reset、remove、execute、getResponse 等生命周期控制。
  • React 集成：可使用可选依赖 @marsidev/react-turnstile。
  • 服务端校验：必须调用 Siteverify API（https://challenges.cloudflare.com/turnstile/v0/siteverify），使用 POST 请求，支持 remoteip、idempotency_key、expectedAction、expectedHostname 等额外校验。
  • 提供 12 个已知问题的预防说明，包括缺少服务端校验、令牌过期、密钥暴露、GET 请求错误、CSP 拦截、小部件崩溃、配置错误、Safari 18 “隐藏 IP”问题、Brave 浏览器问题、Next.js + Jest 不兼容、localhost 未加入白名单、令牌复用等。
  • 附带参考文档与模板：widget-configs.md、error-codes.md、testing-guide.md、react-integration.md、common-patterns.md、advanced-topics.md、setup-checklist.md、migration-guide.md、browser-support.md、mobile-implementation.md，以及 templates/ 下的 Workers 配置、隐式/显式小部件、服务端校验、React 组件、Hono 路由、测试配置等模板，另有 scripts/check-csp.sh 用于检查内容安全策略。

使用方式

资料给出的三步流程如下：

  1. 在 Cloudflare Dashboard（https://dash.cloudflare.com/?to=/:account/turnstile）创建小部件，复制 sitekey 与 secret key；为 dev/staging/production 使用不同小部件；本地测试需显式将 localhost 加入允许域名。
  2. 前端集成：加载 api.js（不得代理或缓存，必须从 Cloudflare CDN 加载），添加 <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>，或使用 ?render=explicit 配合 turnstile.render 进行编程式渲染；小部件会自动创建隐藏字段 cf-turnstile-response。
  3. 服务端校验：使用 POST 向 Siteverify 提交 secret、response（必要时加 remoteip、idempotency_key），检查 outcome.success，并可校验 action 与 hostname；示例中提供了 Cloudflare Workers 的 fetch 处理与 validateTurnstile 函数。

适用场景

  • 表单、登录等需要机器人防护的页面。
  • Cloudflare Workers / Hono 路由的服务端校验。
  • React / Next.js 应用的前端集成。
  • 从 reCAPTCHA（v2）或 hCaptcha 迁移。
  • E2E 测试与 CI/CD 集成（使用测试用 dummy key，如 sitekey 1x00000000000000000000AA）。
  • SPA 的显式小部件生命周期管理与预清除（pre-clearance）。
  • 移动端 WebView（iOS、Android、React Native、Flutter）集成。

限制与约束

  • 必须进行服务端校验，仅客户端验证不安全。
  • secret key 只能保存在后端，不得暴露在前端。
  • 令牌单次使用，且 5 分钟后过期。
  • Siteverify 仅接受 POST，使用 GET 会返回 405。
  • 不得代理或缓存 api.js，必须从 Cloudflare CDN 加载。
  • 必须在用户完成表单后校验令牌，过早校验会造成安全问题。
  • 不得在生产测试中使用生产密钥。
  • 使用 CSP 时需允许 challenges.cloudflare.com（script-src、frame-src、connect-src），否则可能出现错误 200500。
  • 域名必须在白名单内，否则出现错误 110200；本地开发需加入 localhost 或使用 dummy 测试密钥。
  • 部分浏览器/隐私设置可能影响验证，如 Safari 18 的“隐藏 IP”、Brave shields。
  • 必需依赖为空；React、TypeScript、Vue、Angular、Svelte、Nuxt 等绑定为可选项，具体版本资料中有列出（如 @marsidev/react-turnstile@1.3.1、turnstile-types@1.2.3）。
  • 价格、收费情况暂未提供。