验证码
验证码插件
Captcha 插件通过在关键端点添加验证码验证，为您的 Better Auth 系统集成了机器人防护功能。此插件确保只有人类用户可以执行注册、登录或重置密码等操作。当前支持的提供者有：
安装
将插件添加到您的 auth 配置中
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,
},
},
});- 要在客户端实现 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-up/email", "/sign-in/email", "/request-password-reset"]。minScore(可选 - 仅 Google ReCAPTCHA v3): 最低分数阈值。默认值为0.5。siteKey(可选 - 仅 hCaptcha 和 CaptchaFox): 防止使用一个站点密钥生成的令牌在另一处兑换。siteVerifyURLOverride(可选): 覆盖验证码验证请求的端点 URL。