告别糟糕的图形验证码：Cloudflare Turnstile 无感人机验证全栈集成实践

1. 用户访问包含 Turnstile 组件的登录页
   │
   ▼
2. 浏览器后台运行 Cloudflare 零交互 PoW / 行为挑战
   │
   ▼
3. 挑战通过，生成一次性验证令牌 (Turnstile Token)
   │
   ▼
4. 前端表单提交: 将 { username, password, cfTurnstileToken } 发给后端
   │
   ▼
5. 业务后端服务器向 Cloudflare Siteverify 接口发起 POST 鉴权
   │
   ├── [验证失败] ──► 抛出 403 / 拒绝操作，防范重放与伪造
   └── [验证成功] ──► 放行业务逻辑，完成登录/保存

pnpm add @marsidev/react-turnstile

// components/LoginForm.tsx
'use client';
 
import { useState } from 'react';
import { Turnstile } from '@marsidev/react-turnstile';
 
export function LoginForm() {
  const [email, setEmail] = useState('');
  const [token, setToken] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState(false);
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!token) {
      alert('请等待人机验证完成');
      return;
    }
 
    setIsLoading(true);
    try {
      const res = await fetch('/api/login', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          email,
          token, // 携带 Turnstile 生成的令牌
        }),
      });
 
      const data = await res.json();
      if (!res.ok) throw new Error(data.message || '登录失败');
      alert('登录成功！');
    } catch (err: any) {
      alert(err.message);
    } finally {
      setIsLoading(false);
    }
  };
 
  return (
    <form onSubmit={handleSubmit} className="max-w-md space-y-4 p-6 border rounded-xl">
      <h2 className="text-xl font-bold">用户登录</h2>
 
      <input
        type="email"
        placeholder="请输入邮箱"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        required
        className="w-full px-3 py-2 border rounded-md"
      />
 
      {/* Cloudflare Turnstile 验证组件 */}
      <div className="flex justify-center my-2">
        <Turnstile
          siteKey={process.env.NEXT_PUBLIC_CLOUDFLARE_TURNSTILE_SITE_KEY!}
          onSuccess={(t) => setToken(t)}
          onError={() => setToken(null)}
          onExpire={() => setToken(null)}
          options={{
            theme: 'auto',
            size: 'normal',
          }}
        />
      </div>
 
      <button
        type="submit"
        disabled={isLoading || !token}
        className="w-full py-2 bg-blue-600 text-white rounded-md disabled:bg-gray-400"
      >
        {isLoading ? '验证并提交中...' : '登 录'}
      </button>
    </form>
  );
}

// app/api/login/route.ts
import { NextResponse } from 'next/server';
 
interface TurnstileVerifyResponse {
  success: boolean;
  'error-codes'?: string[];
  challenge_ts?: string;
  hostname?: string;
}
 
export async function POST(req: Request) {
  try {
    const { email, token } = await req.json();
 
    if (!token) {
      return NextResponse.json({ success: false, message: '缺少验证码 Token' }, { status: 400 });
    }
 
    const secretKey = process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY!;
 
    // 构造校验表单数据
    const formData = new URLSearchParams();
    formData.append('secret', secretKey);
    formData.append('response', token);
    
    // 可选传入客户端真实 IP，进一步提升防伪造强度
    const clientIp = req.headers.get('cf-connecting-ip') || req.headers.get('x-forwarded-for');
    if (clientIp) {
      formData.append('remoteip', clientIp);
    }
 
    const verifyRes = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
      method: 'POST',
      body: formData,
    });
 
    const verifyResult: TurnstileVerifyResponse = await verifyRes.json();
 
    if (!verifyResult.success) {
      console.warn('Turnstile 校验失败:', verifyResult['error-codes']);
      return NextResponse.json(
        { success: false, message: '人机验证失败，请刷新后重试' },
        { status: 403 }
      );
    }
 
    // 校验成功，放行正常业务逻辑（如校验密码、生成 Session Token）
    return NextResponse.json({ success: true, user: { email } });
  } catch (error: any) {
    return NextResponse.json({ success: false, message: error.message }, { status: 500 });
  }
}