Cloudflare Turnstile 配置完全指南：脚本加载、组件选项与框架集成的实战手册（Codex Skills 仓库深度解析）

Cloudflare Turnstile 配置完全指南脚本加载、组件选项与框架集成的实战手册Codex Skills 仓库深度解析【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以本仓库 Codex Skills 目录中 cloudflare-deploy 技能下的 Turnstile 配置参考文档 为核心骨架系统讲解 Cloudflare Turnstile一种无需用户手动拼图/勾选的人机验证方案的前端配置全流程从四种脚本加载方式、完整的组件 Options 对象、HTML 数据属性映射到 Content Security Policy 与 React / Vue / Svelte / Next.js 框架接入以及 Cloudflare Pages 官方插件。读完本文你将能够独立完成 Turnstile 从「引入脚本 → 渲染组件 → 服务端校验 → 框架集成」的完整落地并规避 token 过期、单次使用、CSP 拦截等常见坑点。一、Turnstile 是什么先理解它在整个技能体系中的定位在本仓库中cloudflare-deploy 是一个「部署应用到 Cloudflare」的整合型技能其 SKILL.md 通过决策树引导 Agent 选择合适产品在 I need security我需要安全能力分支下CAPTCHA alternative → turnstile/。也就是说Turnstile 在本技能中承担的是人机验证/反机器人这一安全职责与 WAF、DDoS、Bot Management、API Shield 并列。依据同目录 turnstile READMETurnstile 是一种用户友好的 CAPTCHA 替代品它在后台运行挑战无需用户交互即可完成验证通过浏览器行为、设备指纹与机器学习等信号自动判断访问者是否为真人。配置文档即本文核心则负责回答「怎么把验证组件渲染到页面上、怎么配置它的行为」。在动手配置之前需要先了解 Turnstile 的三种组件形态源自 README.md因为它们直接决定后续配置方式类型交互方式适用场景Managed托管默认仅在需要时显示复选框表单、登录页——兼顾体验与安全Non-Interactive非交互不可见自动运行无感体验、低风险操作Invisible隐形隐藏通过代码触发预放行Pre-clearance、API 调用、无头环境同时必须记住三条硬性约束源自 README 与 gotchas.mdToken 有效期 5 分钟超过 5 分钟即失效Token 单次使用每个 token 只能被 siteverify 校验一次重复校验会报timeout-or-duplicate必须服务端校验仅靠前端校验可被轻易绕过。二、脚本加载四种方式各取所需配置的起点是引入官方脚本脚本地址统一为https://challenges.cloudflare.com/turnstile/v0/api.js。configuration.md 给出四种加载方式对应不同的渲染控制粒度。1. 基础方式隐式渲染Implicit Renderingscript srchttps://challenges.cloudflare.com/turnstile/v0/api.js async defer/scriptasync defer保证脚本异步加载且不阻塞页面解析。脚本加载后会自动扫描页面中带有classcf-turnstile的元素在页面加载时自动渲染为 Turnstile 组件——这就是「隐式渲染」无需写任何 JavaScript只需在表单里放一个div classcf-turnstile>script srchttps://challenges.cloudflare.com/turnstile/v0/api.js?renderexplicit/script通过 URL 参数renderexplicit关闭自动渲染改为通过window.turnstile.render()手动控制组件渲染的时机与位置。适用于 SPA、动态插入容器、或需要精确控制渲染时机的场景。3. 带加载回调With Load Callbackscript srchttps://challenges.cloudflare.com/turnstile/v0/api.js?onloadmyCallback/script script function myCallback() { // API ready window.turnstile.render(#container, { sitekey: YOUR_SITE_KEY }); } /scriptonload参数指定一个全局回调函数名脚本加载完成、window.turnstileAPI 就绪后立即调用。注意api.md 中的 TypeScript 声明还支持window.onloadTurnstileCallback这种命名约定两种写法等价选择其一保持一致即可。4. 兼容模式Compatibility Modescript srchttps://challenges.cloudflare.com/turnstile/v0/api.js?compatrecaptcha/script加上compatrecaptcha后脚本会额外提供grecaptchaAPI让已接入 Google reCAPTCHA 的老代码可以零改造成本地切换到 Turnstiledrop-in replacement。适合存量项目迁移。三、组件配置完整的 Options 对象与关键选项语义显式渲染window.turnstile.render(container, options)的核心是 Options 对象。configuration.md 给出了完整的配置结构下面按「必填 / 回调 / 外观 / 行为 / 表单集成 / 分析与数据」六个维度完整呈现并补充默认值与取值说明{ // —— 必填 —— sitekey: YOUR_SITE_KEY, // 从 Cloudflare 控制台创建 Widget 后获得的站点密钥 // —— 回调函数 —— callback: (token) {}, // 校验成功token 已就绪在表单提交前一定要等到它 error-callback: (code) {}, // 发生错误code 为错误码 expired-callback: () {}, // token 过期5 分钟 timeout-callback: () {}, // 挑战超时 before-interactive-callback: () {}, // 展示复选框之前触发 after-interactive-callback: () {}, // 用户交互完成后触发 unsupported-callback: () {}, // 浏览器不支持 Turnstile 时触发 // —— 外观 —— theme: auto, // light | dark | auto跟随系统 size: normal, // normal | compact | flexible tabindex: 0, // 键盘 Tab 顺序可访问性 language: auto, // ISO 639-1 语言码如 en或 auto // —— 行为 —— execution: render, // render渲染即开始挑战| execute等 turnstile.execute() 手动触发 appearance: always, // always | execute | interaction-only retry: auto, // auto失败自动重试| never retry-interval: 8000, // 重试间隔毫秒默认 8000 refresh-expired: auto, // auto | manual | never // —— 表单集成 —— response-field: true, // 是否自动生成隐藏 input 存放 token默认 true response-field-name: cf-turnstile-response, // 隐藏 input 的 name服务端据此取值 // —— 分析与数据 —— action: login, // 动作名称用于分析siteverify 响应中原样返回 cData: user-session-123, // 自定义数据siteverify 校验时原样返回 }关键选项深度解读execution挑战触发时机render默认组件渲染后挑战立即开始用户无需等待execute组件渲染后不自动发起挑战必须调用window.turnstile.execute()才触发。适合把挑战推迟到用户点击提交按钮之后配合appearance: execute可实现「先隐藏、提交时才出验证」。appearance可见性策略always默认组件始终可见execute隐藏直到调用execute()interaction-only隐藏直到真正需要用户交互时才展示Managed 类型常用。refresh-expired过期 token 处理auto默认token 过期后自动刷新manual过期后应用需自行调用turnstile.reset()重置never不刷新只触发expired-callback。retry挑战失败重试auto默认挑战失败自动重试never不重试直接触发error-callback。这些选项的取值域与 api.md 中的TurnstileOptionsTypeScript 接口完全一致execution?: render | execute、appearance?: always | execute | interaction-only等TypeScript 项目可直接获得编译期类型检查。四、HTML 数据属性隐式渲染的声明式配置隐式渲染div classcf-turnstile不需要写 JavaScript所有配置通过 data 属性声明。configuration.md 给出了完整的「JavaScript 属性 ↔ HTML 数据属性」映射表以下为全量对照JavaScript 属性HTML 数据属性示例sitekeydata-sitekeydata-sitekeyYOUR_KEYactiondata-actiondata-actionlogincDatadata-cdatadata-cdatasession-123callbackdata-callbackdata-callbackonSuccesserror-callbackdata-error-callbackdata-error-callbackonErrorexpired-callbackdata-expired-callbackdata-expired-callbackonExpiredtimeout-callbackdata-timeout-callbackdata-timeout-callbackonTimeoutthemedata-themedata-themedarksizedata-sizedata-sizecompacttabindexdata-tabindexdata-tabindex0response-fielddata-response-fielddata-response-fieldfalseresponse-field-namedata-response-field-namedata-response-field-nametokenretrydata-retrydata-retryneverretry-intervaldata-retry-intervaldata-retry-interval5000languagedata-languagedata-languageenexecutiondata-executiondata-executionexecuteappearancedata-appearancedata-appearanceinteraction-onlyrefresh-expireddata-refresh-expireddata-refresh-expiredmanual注意数据属性中的回调如data-callbackonSuccess指向的是全局函数名因此隐式渲染要求相关回调函数定义在全局作用域。完整示例div classcf-turnstile >meta http-equivContent-Security-Policy contentdefault-src self; script-src self https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com;gotchas.md 明确把CSP 拦截列为「Widget 不渲染」的头号原因之一其余常见原因还包括sitekey 错误、file://协议下无法加载应改用http://本地服务。若组件不渲染请优先按此排查。六、框架级接入React / Vue / Svelte / Next.jsReact官方推荐的社区封装包为marsidev/react-turnstilenpm install marsidev/react-turnstileimport Turnstile from marsidev/react-turnstile; Turnstile siteKeyYOUR_SITE_KEY onSuccess{(token) console.log(token)} /Vuenpm install vue-turnstiletemplate VueTurnstile site-keyYOUR_SITE_KEY successonSuccess / /template script setup import VueTurnstile from vue-turnstile; /scriptSveltenpm install svelte-turnstilescript import Turnstile from svelte-turnstile; /script Turnstile siteKeyYOUR_SITE_KEY on:turnstile-callback{handleToken} /Next.jsApp Router由于window.turnstile只在浏览器端存在必须用use client声明客户端组件并在useEffect中完成渲染与清理源自 configuration.md// app/components/TurnstileWidget.tsx use client; import { useEffect, useRef } from react; export default function TurnstileWidget({ sitekey, onSuccess }) { const ref useRefHTMLDivElement(null); useEffect(() { if (ref.current window.turnstile) { const widgetId window.turnstile.render(ref.current, { sitekey, callback: onSuccess }); return () window.turnstile.remove(widgetId); } }, [sitekey, onSuccess]); return div ref{ref} /; }框架接入的三大坑源自 gotchas.mdReact 组件重挂载丢 token组件因 state 变化重新渲染时验证 token 会丢失。解决思路是用useRef锁定渲染生命周期仅在首次挂载时render、卸载时removeReact StrictMode 双重渲染开发模式下 StrictMode 会执行两次 effect必须提供清理函数return () window.turnstile.remove(widgetId)避免出现两个叠加的组件实例Next.js SSR 水合问题window.turnstile在服务端渲染阶段为undefined组件必须use client或使用dynamic(..., { ssr: false })动态导入。七、Cloudflare Pages 插件一行代码接入服务端校验如果站点部署在 Cloudflare Pages可以直接使用官方中间件插件把验证逻辑放进 Functions 中间件无需手写 siteverify 调用源自 configuration.mdnpm install cloudflare/pages-plugin-turnstile// functions/_middleware.ts import turnstilePlugin from cloudflare/pages-plugin-turnstile; export const onRequest turnstilePlugin({ secret: YOUR_SECRET_KEY, onError: () new Response(CAPTCHA failed, { status: 403 }) });只要请求通过_middleware.ts插件就会自动校验请求携带的 Turnstile token校验失败直接返回 403。注意secret是服务端密钥绝不能出现在客户端代码中详见下文安全底线。八、配合服务端校验让配置真正闭环配置文档负责「前端渲染」但人机验证的安全闭环必须落在服务端。结合 api.md 与 patterns.mdsiteverify 的完整流程如下端点POST https://challenges.cloudflare.com/turnstile/v0/siteverify请求体字段字段类型说明secretstring你的密钥绝不暴露给客户端responsestring前端提交的 token来自cf-turnstile-response隐藏字段remoteipstring用户 IP可选但建议传idempotency_keystring幂等校验唯一键可选响应字段success校验结果、challenge_ts挑战时间戳 ISO、hostname解决验证的域名、error-codes失败时的错误码数组、action组件配置的动作名、cdata组件配置的自定义数据。Cloudflare Workers 服务端校验示例源自 README 与 patterns.mdexport default { async fetch(request) { const formData await request.formData(); const token formData.get(cf-turnstile-response); const result await fetch(https://challenges.cloudflare.com/turnstile/v0/siteverify, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ secret: env.TURNSTILE_SECRET, response: token, remoteip: request.headers.get(CF-Connecting-IP) }) }); const validation await result.json(); if (!validation.success) { return new Response(Invalid CAPTCHA, { status: 400 }); } // Process form... } }常见错误码速查源自 api.md错误码原因处理missing-input-secret未提供 secret请求中带上secretinvalid-input-secretsecret 错误在控制台核对密钥missing-input-response未提供 token带上responsetokeninvalid-input-responsetoken 非法/格式错误确认来自组件的 tokentimeout-or-duplicatetoken 过期5 分钟或重复使用生成新 token只能校验一次internal-errorCloudflare 服务端错误指数退避重试bad-request请求格式错误检查 JSON/表单编码四条不可妥协的安全底线源自 gotchas.md禁止只做前端校验客户端校验可被轻易绕过必须服务端调用 siteverify禁止暴露 secret密钥只存在于服务端环境变量绝不写入前端代码禁止复用 tokentoken 单次有效提交失败后调用window.turnstile.reset(widgetId)生成新 token必须处理过期配置refresh-expired: auto或在expired-callback中重置组件。环境区分测试密钥源自 README 与 patterns.md测试密钥在 localhost 与任意域名均可用严禁用于生产类型密钥行为Site Key始终通过1x00000000000000000000AA组件成功token 可通过校验Site Key始终拦截2x00000000000000000000AB组件可见地失败Site Key强制挑战3x00000000000000000000FF总是展示交互挑战Secret Key测试1x0000000000000000000000000000000AA校验测试 token生产/测试切换建议按环境变量区分const SITE_KEY process.env.NODE_ENV production ? process.env.TURNSTILE_SITE_KEY : 1x00000000000000000000AA;九、调试三板斧与约束速查调试建议源自 gotchas.md组件渲染时同时注册callback/error-callback/expired-callback/timeout-callback并输出日志第一时间定位状态用window.turnstile.getResponse(widgetId)检查 token 是否就绪用window.turnstile.isExpired(widgetId)检查是否过期打开浏览器 Network 面板确认api.js返回 200、观察 siteverify 请求/响应、排查 4xx/5xx。约束速查表约束值影响Token 有效期5 分钟过期需重新生成Token 使用次数单次不能重复校验同一 token组件尺寸normal 300×65pxcompact 130×120px布局时预留空间十、总结Turnstile 的配置本质上是一条「加载脚本 → 渲染组件隐式/显式→ 收集 token → 服务端 siteverify 校验」的闭环链路configuration.md 解决了链路的前半段脚本加载、Options 配置、数据属性、CSP、框架接入、Pages 插件而后半段的校验细节可继续阅读同目录的 api.md客户端 API 与 siteverify 接口、patterns.md表单集成与预放行模式、gotchas.md排错与反模式。把「5 分钟过期、单次使用、必须服务端校验、密钥不出服务端」这四条底线刻在脑海里你的 Turnstile 接入就能既顺滑又安全。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考