验证码

验证码插件

Captcha 插件通过在关键端点添加验证码验证，为您的 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: "[email protected]",
    password: "secure-password",
    fetchOptions: { 
        headers: { 
            "x-captcha-response": turnstileToken, 
        }, 
    }, 
});

要在客户端实现 Cloudflare Turnstile，请参考官方 Cloudflare Turnstile 文档或使用类似 react-turnstile 的库。
要在客户端实现 Google reCAPTCHA，请参考官方 Google reCAPTCHA 文档或使用类似 react-google-recaptcha (v2) 和 react-google-recaptcha-v3 (v3) 的库。
要在客户端实现 hCaptcha，请参考官方 hCaptcha 文档或使用类似 @hcaptcha/react-hcaptcha 的库。
要在客户端实现 CaptchaFox，请参考官方 CaptchaFox 文档或使用类似 @captchafox/react 的库。

工作原理

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

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

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

插件选项

provider（必填）：您的验证码提供商。
secretKey（必填）：您的提供商用于服务端验证的密钥。
endpoints（可选）：替换强制执行验证码验证的默认路径数组。如果设置，则仅保护指定的路径。除非路径包含通配符，否则路径必须完全匹配，例如 /sign-in/* 匹配一个层级，/sign-in/** 匹配嵌套路由。默认值为 ["/sign-up/email", "/sign-in/email", "/request-password-reset"]。
minScore（可选 — 仅适用于 Google ReCAPTCHA v3）：最低分数阈值。默认值为 0.5。
siteKey（可选 — 仅适用于 hCaptcha 和 CaptchaFox）：防止在一个 sitekey 上签发的令牌在其他位置被兑换。
siteVerifyURLOverride（可选）：覆盖验证码验证请求的端点 URL。

On this page

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