在 Next.js 14 中集成 Cloudflare Turnstile如果你用过国外的 SaaS 工具，一定见过这张

什么是 Cloudflare Turnstile

如果你用过国外的 SaaS 工具，一定见过下面这张动图的页面：

这就是 Cloudflare Turnstile，它是 Cloudflare 在 2022 年推出的一个检测机器人的验证服务。

如果你用过 Google reCAPTCHA，一定会看烦了里面的楼梯、斑马线、巴士、摩托车的图片，那就好像我们在免费给谷歌提供 AI 图片标记似的。

Cloudflare Turnstile 就是用来替代 Google reCAPTCHA 的，Turnstile 只需要用户用鼠标点击一下就能完成验证，就像开头的那张动图。这种做法真正在用户友好和安全校验之间做到了平衡。

在开始我们今天的教程前，还需要先罗列一下 Cloudflare Turnstile 的优点和使用场景，它们正是我们要学习使用 Cloudflare Turnstile 的理由；

优点：

• 用户体验好：用户只需要点击一下，甚至可能感觉不到验证的存在
• 注重隐私：Turnstile 不会收集用户的个人信息
• 智能验证：利用 Cloudflare 的全球网络数据来判断访问者是否为机器人
• 易于集成：提供了简单的 API 和多种集成选项
• 免费使用：对所有 Cloudflare 用户免费
• 开放兼容：Turnstile 提供了与 reCAPTCHA 兼容的 API，便于从 reCAPTCHA 迁移

使用场景：

• 用户注册和登录：在用户创建新账户或登录时使用 Turnstile 可以有效防止自动化脚本批量注册或进行暴力破解攻击

• 评论系统：Turnstile 可以有效阻止机器人大量发布广告或恶意链接

• 电子商务交易：在线购物网站可以在结账过程中使用Turnstile，这样助于防止刷单、账户劫持等欺诈行为

• 文件上传：使用Turnstile可以防止自动化工具滥用上传功能

• API保护：使用Turnstile来限制API的滥用

集成 Cloudflare Turnstile

1. 获取 Turnstile 站点密钥

首先，登录 Cloudflare 控制台，创建一个 Turnstile 站点，获取站点密钥(Site Key)和密钥(Secret Key)。

2. 安装依赖

npm install @marsidev/react-turnstile

3. 创建 Turnstile 组件

新建一个文件，比如 components/TurnstileWidget.tsx：

import React from 'react';
import { Turnstile } from '@marsidev/react-turnstile';

interface TurnstileWidgetProps {
  onVerify: (token: string) => void;
}

const TurnstileWidget: React.FC<TurnstileWidgetProps> = ({ onVerify }) => {
  return (
    <Turnstile
      siteKey={process.env.NEXT_PUBLIC_TURNSTILE_SITE_KEY || ''}
      onSuccess={onVerify}
    />
  );
};

export default TurnstileWidget;

4. 在表单中使用 Turnstile

修改表单组件，例如 components/ContactForm.tsx：

import React, { useState } from 'react';
import TurnstileWidget from './TurnstileWidget';

const ContactForm = () => {
  const [turnstileToken, setTurnstileToken] = useState<string | null>(null);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!turnstileToken) {
      alert('请等待验证完成');
      return;
    }
    // 这里处理表单提交逻辑，记得将 turnstileToken 发送到后端验证
    console.log('表单提交', { turnstileToken });
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* 其他表单字段 */}
      <TurnstileWidget onVerify={setTurnstileToken} />
      <button type="submit">提交</button>
    </form>
  );
};

export default ContactForm;

5. 创建 API 路由进行验证

在 app/api 目录下创建 verify-turnstile.ts:

import { NextResponse } from 'next/server';
import axios from 'axios';

export async function POST(req: Request) {
  const body = await req.json();
  const { token } = body;

  try {
    const response = await axios.post(
      'https://challenges.cloudflare.com/turnstile/v0/siteverify',
      new URLSearchParams({
        secret: process.env.TURNSTILE_SECRET_KEY || '',
        response: token,
      }),
      {
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      }
    );

    if (response.data.success) {
      return NextResponse.json({ success: true });
    } else {
      return NextResponse.json({ success: false, error: '验证失败' }, { status: 400 });
    }
  } catch (error) {
    console.error('验证出错:', error);
    return NextResponse.json({ success: false, error: '服务器错误' }, { status: 500 });
  }
}

6. 一些高级用法

• 本地化支持

  如果你的网站有做国际化，那么你也可以为 Turnstile 配置展示的语言：

  <Turnstile
    // ...其他属性
    options={{
      language: 'zh-CN', // 设置为中文
    }}
  />
  

• 主题定制

  你可以通过自定义样式来修改 Turnstile 的外观，例如：

  .cf-turnstile {
    margin-top: 20px;
    margin-bottom: 20px;
  }
  

总结

Cloudflare 被程序员们称为「赛博佛祖」，是因为他们提供了很多程序员需要的免费服务，Cloudflare Turnstile 也是其中之一，也是从 Cloudflare Turnstile 推出后，很多个人或小团队的产品都从 Google reCAPTCHA 迁移走了。现在我们海外网站冲浪的时候，会发现 Cloudflare Turnstile 出现的频率比 Google reCAPTCHA 的出现频率要高得多，可见 Cloudflare Turnstile 已经获得市场的认可了。

从本文的教程也能看出来，Next.js 项目集成 Cloudflare Turnstile 并没有什么难度，所以如果你的网站或者产品有稳定的用户，不妨花半小时为网站添加一个安全校验。

关于我

我是一名前端工程师，Next.js 手艺人，AI降临派。

今年致力于 Next.js 和 Node.js 领域的开源项目开发和知识分享。