React Turnstile终极入门：从安装到实现验证码的5分钟教程

React Turnstile终极入门：从安装到实现验证码的5分钟教程

【免费下载链接】react-turnstileCloudflare Turnstile integration for React.项目地址: https://gitcode.com/gh_mirrors/re/react-turnstile

React Turnstile是一个专为React应用设计的Cloudflare Turnstile验证码集成库，提供轻量级、注重隐私的reCAPTCHA替代方案，支持自动脚本注入、TypeScript类型定义和SSR兼容性。通过本教程，你将在5分钟内完成从安装到实现验证码功能的全过程，为你的React应用添加安全可靠的人机验证机制。

1. 快速安装React Turnstile

首先，使用npm或pnpm安装React Turnstile库。打开终端，在你的React项目根目录中执行以下命令：

npm install @marsidev/react-turnstile # 或者使用pnpm pnpm install @marsidev/react-turnstile

这个轻量级库会自动处理Cloudflare Turnstile脚本的加载和管理，无需额外配置复杂的脚本引入逻辑。

2. 获取Cloudflare Turnstile Site Key

使用React Turnstile前，你需要从Cloudflare获取一个site key：

1. 访问Cloudflare Turnstile dashboard
2. 注册或登录你的Cloudflare账号
3. 创建新的Turnstile站点，获取你的siteKey（格式类似1x00000000000000000000AA）

site key是连接你的应用与Cloudflare Turnstile服务的重要凭证，确保妥善保管。

3. 实现基础验证码组件

安装完成并获取site key后，你可以在React组件中轻松实现Turnstile验证码。最简单的实现只需一行代码：

import { Turnstile } from '@marsidev/react-turnstile' function MyForm() { return ( <form> {/* 其他表单字段 */} <Turnstile siteKey="YOUR_SITE_KEY" /> <button type="submit">提交</button> </form> ) }

将YOUR_SITE_KEY替换为你从Cloudflare获取的实际site key，一个基础的验证码组件就添加完成了。React Turnstile会自动处理脚本加载、 widget渲染和状态管理。

4. 处理验证成功回调

当用户成功完成验证后，你需要获取验证token并发送到服务器进行验证。使用onSuccess回调函数可以轻松实现这一功能：

import { useState } from 'react' import { Turnstile } from '@marsidev/react-turnstile' function MyForm() { const [token, setToken] = useState(null) const [isSubmitting, setIsSubmitting] = useState(false) const handleSubmit = async (e) => { e.preventDefault() if (!token) return setIsSubmitting(true) try { // 发送token到服务器进行验证 const response = await fetch('/api/verify', { method: 'POST', body: JSON.stringify({ token /* 其他表单数据 */ }) }) // 处理成功响应 } catch (error) { // 处理错误 } finally { setIsSubmitting(false) } } return ( <form onSubmit={handleSubmit}> {/* 其他表单字段 */} <Turnstile siteKey="YOUR_SITE_KEY" onSuccess={(token) => setToken(token)} /> <button type="submit" disabled={!token || isSubmitting}> 提交 </button> </form> ) }

5. 服务器端验证实现

Turnstile验证必须在服务器端完成，以确保安全性。以下是一个使用Node.js的简单验证示例：

// 服务器端代码 (例如: Next.js API路由) export async function POST(request) { const { token } = await request.json() // 向Cloudflare验证token const response = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ secret: 'YOUR_SECRET_KEY', // 你的Cloudflare密钥 response: token, remoteip: request.ip }) }) const data = await response.json() if (data.success) { // token验证成功，处理后续逻辑 return Response.json({ success: true }) } else { // token验证失败 return Response.json({ success: false }, { status: 400 }) } }

6. 自定义验证码外观和行为

React Turnstile提供多种自定义选项，让验证码更符合你的应用风格：

调整尺寸

{/* 标准尺寸 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ size: 'normal' }} /> {/* 紧凑尺寸 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ size: 'compact' }} /> {/* 灵活尺寸 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ size: 'flexible' }} /> {/* 隐形验证 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ size: 'invisible' }} />

主题设置

{/* 自动主题（跟随系统） */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ theme: 'auto' }} /> {/* 浅色主题 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ theme: 'light' }} /> {/* 深色主题 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ theme: 'dark' }} />

语言设置

{/* 自动检测语言 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ language: 'auto' }} /> {/* 英语 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ language: 'en' }} /> {/* 西班牙语 */} <Turnstile siteKey="YOUR_SITE_KEY" options={{ language: 'es' }} />

7. 常见问题与解决方案

问题：Token过期或已使用

Turnstile tokens是一次性使用的，通常在5分钟后过期。解决方法是在提交表单时获取token，而不是在验证成功时：

import { useRef } from 'react' import { Turnstile } from '@marsidev/react-turnstile' function MyForm() { const turnstileRef = useRef(null) const handleSubmit = async (e) => { e.preventDefault() // 在提交时获取token const token = turnstileRef.current?.getResponse() if (!token) { alert('请完成验证码验证') return } // 发送token到服务器... } return ( <form onSubmit={handleSubmit}> {/* 其他表单字段 */} <Turnstile ref={turnstileRef} siteKey="YOUR_SITE_KEY" /> <button type="submit">提交</button> </form> ) }

问题：在Next.js中使用时出现SSR错误

在Next.js中使用时，确保在客户端组件中使用Turnstile，并添加'use client'指令：

'use client' import { Turnstile } from '@marsidev/react-turnstile' export default function MyClientComponent() { return <Turnstile siteKey="YOUR_SITE_KEY" /> }

总结

通过本教程，你已经学会了如何在React应用中快速集成Cloudflare Turnstile验证码。从安装库、获取site key，到实现基础验证功能和自定义外观，整个过程不到5分钟就能完成。React Turnstile提供了简单易用的API，同时保持了高度的可定制性，让你能够轻松为应用添加安全的人机验证功能。

更多高级用法和详细文档，请参考项目的官方文档：docs/。如果你需要处理多个验证码组件或更复杂的验证逻辑，可以查阅packages/lib/skills/multiple-widgets/SKILL.md和packages/lib/skills/token-lifecycle/SKILL.md获取更多指导。

【免费下载链接】react-turnstileCloudflare Turnstile integration for React.项目地址: https://gitcode.com/gh_mirrors/re/react-turnstile