BETTER-AUTH.

验证码

验证码插件

验证码插件通过为关键端点添加验证码验证，将机器人保护集成到您的 Better Auth 系统中。该插件确保只有人类用户才能执行注册、登录或重置密码等操作。目前支持以下提供商：

此插件开箱即用，支持 邮箱与密码 认证。若要在其他认证方式下使用，您需要在插件选项中配置 endpoints 数组。

安装

将插件添加到您的 auth 配置中

auth.ts
import { betterAuth } from "better-auth";
import { captcha } from "better-auth/plugins"; 

export const auth = betterAuth({
    plugins: [
        captcha({ 
            provider: "cloudflare-turnstile", // 或者 google-recaptcha、hcaptcha、captchafox
            secretKey: process.env.TURNSTILE_SECRET_KEY!, 
        }), 
    ],
});

将验证码令牌添加到您的请求头

现在不再需要 x-captcha-user-remote-ip 头 — IP 地址由服务端自动检测。

在所有受保护端点的请求头中添加验证码令牌。以下示例展示了在 signIn 请求中如何包含：

import { authClient } from "@/lib/auth-client"

await authClient.signIn.email({
    email: "user@example.com",
    password: "secure-password",
    fetchOptions: { 
        headers: { 
            "x-captcha-response": turnstileToken, 
        }, 
    }, 
});

工作原理

该插件作为中间件运行：拦截所有对配置端点的 POST 请求（请参见 插件选项 中的 endpoints）。

它通过调用验证码提供商的 /siteverify 接口，在服务器端验证验证码令牌。

  • 如果令牌缺失、被验证码提供商拒绝，或 /siteverify 端点不可用，插件将返回错误并中断请求。
  • 如果令牌被验证码提供商接受，中间件返回 undefined，表示请求允许继续处理。

插件选项

  • provider（必填）：您的验证码提供商。
  • secretKey（必填）：用于服务器端验证的提供商密钥。
  • endpoints（可选）：替换默认的验证码验证路径数组。设置后，只有指定路径会被保护。默认值为 ["/sign-up/email", "/sign-in/email", "/request-password-reset"]。
  • minScore（可选 — 仅适用于 Google ReCAPTCHA v3）：最低分数阈值。默认值为 0.5。
  • siteKey（可选 — 仅适用于 hCaptcha 和 CaptchaFox）：防止一个 sitekey 出具的令牌在其他 sitekey 上被使用。
  • siteVerifyURLOverride（可选）：覆盖验证码验证请求的端点 URL。
在 GitHub 上编辑

本页目录

安装
将插件添加到您的 auth 配置中
将验证码令牌添加到您的请求头
工作原理
插件选项