还在为复杂的 CAPTCHA 验证困扰您的用户体验吗？Cloudflare Turnstile 为我们带来了一个优雅的解决方案。作为新一代的智能验证服务，它不仅能有效识别并拦截恶意机器人，更重要的是能让真实用户享受到丝滑般的网站体验。
为什么选择 Turnstile? 🚀 零感知验证 – 无需传统的图片识别验证码
🔒 强大的安全防护 – 智能识别并阻挡自动化攻击
🌐 通用性强 – 可在任何网站使用，不限于 Cloudflare 的站点
⚡ 性能出众 – 对网站性能影响微乎其微
这篇教程将带您一步步在 Next.js 项目中集成 Turnstile。虽然过程相对简单，但基于实践经验，我们会重点关注一些容易被忽视的技术细节，帮助您实现真正完美的集成。
这里的markdown排版不太好用，可以我的博客阅读体验会好一些
一.创建 Cloudflare 账户并配置 Turnstile 首先，您需要：
创建或登录 Cloudflare 账户–访问 Turnstile 控制面板–点击”添加小组件”创建新的验证组件
创建组件
在小部件设置中，添加您的域并选择“托管”模式，确保将其添加localhost到您的域以用于开发目的。
设置模式
二. 获取必要的密钥 在创建验证组件后，您将获得两个重要的密钥：
Site Key: 用于客户端集成
Secret Key: 用于服务端验证
获取密钥
三. 项目结构设计 在开始编码之前，让我们先了解一下完整的项目结构
带插入图片
四.初始化一个nextjs项目,并添加环境变量 在开始集成 Turnstile 之前，我们需要先创建并配置一个 Next.js 项目。
创建 Next.js 项目
使用 create-next-app 创建项目
npx create-next-app@latest my-turnstile-app cd my-turnstile-app 添加env环境变量 在env文件中添加刚才获取的key
NEXT_PUBLIC_TURNSTILE_SITE_KEY=your_site_key_here TURNSTILE_SECRET_KEY=your_secret_key_here
五.定义接口 首先让我们定义一个接口组件，这个接口将作为我们的基础验证组件。它主要提供以下功能：
支持自定义验证栏的背景颜色（深色/浅色主题） 提供多语言支持，方便国际化 集成 Turnstile 的回调机制，处理验证结果
'use client'; import Script from 'next/script'; import { useCallback, useEffect, useRef } from 'react'; interface TurnstileWidgetProps { onVerify: (token: string) => void; theme?: 'light' | 'dark'; language?: string; } const TurnstileWidget: React.FC<TurnstileWidgetProps> = ({ onVerify, theme = 'dark', language = 'zh-CN' }) => { const divRef = useRef<HTMLDivElement>(null); const renderWidget = useCallback(() => { if (divRef.current && window.turnstile) { window.turnstile.render(divRef.current, { sitekey: process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY as string, callback: onVerify, theme, language, }); } }, [theme, language, onVerify]); useEffect(() => { // 只在 turnstile 可用时渲染 if (window.turnstile) { renderWidget(); } const currentRef = divRef.current; // 清理函数：组件卸载或依赖项改变时移除 widget return () => { if (currentRef) { window.turnstile?.remove(currentRef); } }; }, [renderWidget, theme, language, onVerify]); return (<> <Script src="https://challenges.cloudflare.com/turnstile/v0/api.js" onLoad={ renderWidget } /> <div ref={divRef} /> </>); }; export default TurnstileWidget; 这个接口组件使用了 Next.js 的 Script 组件来按需加载 Turnstile 的脚本，这样可以优化页面加载性能。同时，我们还实现了完整的生命周期管理，确保组件在卸载时能够正确清理资源。
六.定义表单组件 接下来，我们创建一个实际的表单组件来展示如何使用 Turnstile 验证。这个组件的主要特点包括：
集成了我们刚才创建的 Turnstile 接口组件 实现了完整的表单状态管理 提供了友好的加载和错误状态提示 使用 TypeScript 确保类型安全
'use client'; import { useState, FormEvent } from 'react'; import TurnstileWidget from './TurnstileWidget'; interface FormData { email: string; password: string; } interface ApiResponse { message?: string; error?: string; } // 添加状态类型 type StatusType = 'success' | 'error' | ''; const ContactForm = () => { const [formData, setFormData] = useState<FormData>({ email: '', password: '', }); const [turnstileToken, setTurnstileToken] = useState<string>(''); const [status, setStatus] = useState<{ type: StatusType; message: string }>({ type: '', message: '' }); const [isSubmitting, setIsSubmitting] = useState<boolean>(false); const handleSubmit = async (e: FormEvent<HTMLFormElement>) => { e.preventDefault(); if (!turnstileToken) { setStatus({ type: 'error', message: '请完成人机验证' }); return; } setIsSubmitting(true); try { const response = await fetch('/api/contact', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ ...formData, turnstileToken, }), }); const data: ApiResponse = await response.json(); if (response.ok) { setStatus({ type: 'success', message: '提交成功！' }); setFormData({ email: '', password: '' }); } else { setStatus({ type: 'error', message: `错误: ${data.error || '未知错误'}` }); } } catch (error) { setStatus({ type: 'error', message: '提交失败，请重试' }); console.error('Form submission error:', error); } finally { setIsSubmitting(false); } }; return ( <form onSubmit={handleSubmit} className="mx-auto mt-16 max-w-xl sm:mt-20"> <div className="grid grid-cols-1 gap-x-8 gap-y-6 sm:grid-cols-2"> <div className="sm:col-span-2"> <label htmlFor="email" className="block text-sm/6 font-semibold text-gray-900"> 邮箱 </label> <div className="mt-2.5"> <input type="email" id="email" value={formData.email} onChange={(e) => setFormData(prev => ({ ...prev, email: e.target.value }))} required className="block w-full rounded-md border-0 px-3.5 py-2 text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-indigo-600 sm:text-sm/6" /> </div> </div> <div className="sm:col-span-2"> <label htmlFor="password" className="block text-sm/6 font-semibold text-gray-900"> 密码 </label> <div className="mt-2.5"> <input type="password" id="password" value={formData.password} onChange={(e) => setFormData(prev => ({ ...prev, password: e.target.value }))} required className="block w-full rounded-md border-0 px-3.5 py-2 text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 placeholder:text-gray-400 focus:ring-2 focus:ring-inset focus:ring-indigo-600 sm:text-sm/6" /> </div> </div> <div className="sm:col-span-2"> <TurnstileWidget onVerify={setTurnstileToken} theme="dark" language='en' /> </div> {status.message && ( <div className="sm:col-span-2"> <p className={`text-sm ${status.type === 'error' ? 'text-red-600' : 'text-green-600'}`}> {status.message} </p> </div> )} </div> <div className="mt-10"> <button type="submit" disabled={isSubmitting} className={`block w-full rounded-md px-3.5 py-2.5 text-center text-sm font-semibold text-white shadow-sm ${ isSubmitting ? 'bg-indigo-400 cursor-not-allowed' : 'bg-indigo-600 hover:bg-indigo-500 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600' }`} > {isSubmitting ? '提交中...' : '提交'} </button> </div> </form> ); }; export default ContactForm; 组件中包含了一些关键的状态处理,表单数据状态管理,验证token的存储和处理,提交状态的追踪,错误信息的展示
七.定义 API 路由
为了处理表单提交，我们需要创建一个后端 API 路由。这个路由主要负责：
接收前端提交的表单数据和验证token
与 Cloudflare 服务器通信验证 token 的有效性
处理验证结果并返回适当的响应
然后定义一个API 路由类型和实现
interface TurnstileVerificationResponse { success: boolean; error_codes?: string[]; challenge_ts?: string; hostname?: string; } interface RequestBody extends FormData { turnstileToken: string; } export async function POST(request: Request) { try { const body: RequestBody = await request.json(); const { turnstileToken, ...formData } = body; // 验证 Turnstile token const verificationResponse = await fetch( 'https://challenges.cloudflare.com/turnstile/v0/siteverify', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ secret: process.env.TURNSTILE_SECRET_KEY, response: turnstileToken, }), } ); const verificationData: TurnstileVerificationResponse = await verificationResponse.json(); if (!verificationData.success) { console.error('Turnstile verification failed:', verificationData['error_codes']); return Response.json( { error: '验证码验证失败' }, { status: 400 } ); } // 验证通过，处理表单数据 // 这里添加你的业务逻辑，比如发送邮件或保存到数据库 console.log(formData) return Response.json({ message: '提交成功' }); } catch (error) { console.error('API route error:', error); return Response.json( { error: '服务器错误' }, { status: 500 } ); } } 在这个部分，我们重点关注了几个安全相关的问题：
确保所有请求都经过 Turnstile 验证,妥善处理验证失败的情况,提供清晰的错误信息.
八.创建测试页面
最后，我们创建一个测试页面来集成所有组件。
import ContactForm from "../components/ContactForm"; export default function ContactPage() { return ( <div className="container mx-auto p-4"> <h1 className="text-2xl font-bold mb-4">联系我们</h1> <ContactForm /> </div> ); } 九.本地运行测试
结语
原文通过这个教程，我们不仅完成了 Turnstile 的基础集成，更重要的是掌握了一些实用的开发技巧。希望这些内容能帮助您在项目中构建更安全、更友好的用户验证机制。在实际部署时候，需要注意确保环境变量正确配置,检查域名设置是否包含了所有需要的域名. 如果您在集成过程中遇到任何问题，欢迎在评论区留言讨论。