better-auth

better-auth

Package：[email protected]（自 v1.4.0 起仅支持 ESM） 文档：https://better-auth.com/docs | GitHub：https://github.com/better-auth/better-auth

环境配置

变量	用途
BETTER_AUTH_SECRET	加密密钥（至少 32 个字符）。生成命令：openssl rand -base64 32
BETTER_AUTH_URL	基础 URL（例如，https://example.com）

只有在未设置环境变量时，才在配置中定义 baseURL/secret。CLI 会在以下位置查找 auth.ts：./、./lib、./utils 或 ./src。

核心配置选项

选项	说明
appName	可选的显示名称
baseURL	仅在未设置 BETTER_AUTH_URL 时使用
basePath	默认值为 /api/auth。设置为 / 可用于根路径。
secret	仅在未设置 BETTER_AUTH_SECRET 时使用
database	必需，除非使用无状态模式（v1.4+）
secondaryStorage	用于会话和速率限制的 Redis/KV
emailAndPassword	设置为 { enabled: true } 以启用
socialProviders	{ google: { clientId, clientSecret }, ... }
plugins	插件数组
trustedOrigins	CSRF 允许列表

插件参考

插件	描述
twoFactor	TOTP、电子邮件 OTP、备用代码
organization	多租户组织、团队、邀请、RBAC
admin	用户管理、模拟用户、封禁
passkey	基于 WebAuthn 的无密码登录
magicLink	基于电子邮件的无密码登录
jwt	支持密钥轮换和 JWKS 的 JWT 令牌
oauthProvider	构建自己的 OAuth 2.1 提供方（独立的 @better-auth/oauth-provider 软件包）
sso	企业 SSO，支持 OIDC、OAuth2、SAML 2.0（独立的 @better-auth/sso 软件包）
scim	企业用户配置（独立的 @better-auth/scim 软件包）
stripe	支付和订阅管理
bearer	面向移动端/CLI 的 API 令牌身份验证
apiKey	支持速率限制的基于令牌的身份验证
oneTap	Google One Tap 便捷登录
anonymous	无需个人身份信息的访客用户访问
genericOAuth	支持 PKCE 的自定义 OAuth 提供方
emailOTP	基于电子邮件的一次性密码身份验证
phoneNumber	基于电话/SMS 的 OTP 登录
username	基于用户名的登录（电子邮件登录的替代方式）
multiSession	在同一浏览器中使用多个账户
openAPI	位于 /api/auth/reference 的交互式 API 文档

会话策略

策略	格式	使用场景
紧凑型（默认）	Base64url + HMAC-SHA256	体积最小、速度最快
JWT	标准 JWT	可互操作
JWE	A256CBC-HS512 加密	安全性最高

快速开始

对于新项目或首次设置 Better Auth，请使用官方交互式设置技能：

npx skills add better-auth/skills -s create-auth-skill

此技能会引导你完成框架检测、数据库选择、身份验证方式选择、插件设置，并生成初始配置。

反模式

反模式	正确做法
使用 d1Adapter	使用 provider: "sqlite" 的 Drizzle 或 Kysely 适配器
在配置中使用表名	使用 ORM 模型名，而非数据库表名
更改插件后忘记运行 CLI	重新运行 npx @better-auth/cli@latest generate
未将 tanstackStartCookies() 设为最后一个插件	它必须是数组中的最后一个插件（TanStack Start）
通过 session 检查登录状态	检查 session?.user —— session 对象始终为真值
缺少 nodejs_compat 标志	Cloudflare Workers 的 wrangler.toml 中必须设置
在身份验证中使用 Kysely CamelCasePlugin	使用不带该插件的独立 Kysely 实例
使用旧的 reactStartCookies 导入	在 v1.4.14 中，已从 better-auth/tanstack-start 将其重命名为 tanstackStartCookies

常见错误

错误	正确做法
环境变量已设置时仍在配置中设置 baseURL 和 secret	仅当未设置 BETTER_AUTH_URL 和 BETTER_AUTH_SECRET 环境变量时，才在配置中定义这些值
在 better-auth v1.4+ 中使用 CommonJS require 语法	better-auth 自 v1.4.0 起仅支持 ESM；只能使用 import 语法
添加或更改插件后未重新运行 CLI generate	更改插件后，务必运行 npx @better-auth/cli@latest generate 以更新数据库架构
通过检查 session 对象是否为真值来检测登录状态	改为检查 session?.user；session 对象本身始终为真值
在 Cloudflare D1 中直接使用 d1Adapter	为兼容 D1，请使用 provider: "sqlite" 的 Drizzle 或 Kysely 适配器

破坏性变更

版本	变更
v1.4.14	reactStartCookies 重命名为 tanstackStartCookies（从 better-auth/tanstack-start 导入）
v1.4.6	allowImpersonatingAdmins 默认值为 false
v1.4.0	仅支持 ESM（不支持 CommonJS）；SSO、SCIM、OAuth Provider 已移至独立软件包
v1.3.0	多团队表结构：需要新增 teamMembers 表

委派

处理身份验证时，请委派给：

• application-security — 安全架构和威胁建模
• database — Drizzle ORM 架构和迁移
• tanstack-start — TanStack Start 集成模式

资源

• 文档：https://better-auth.com/docs
• 选项参考：https://better-auth.com/docs/reference/options
• LLMs.txt：https://better-auth.com/llms.txt
• 更新日志：https://www.better-auth.com/changelogs
• TanStack Start：https://www.better-auth.com/docs/integrations/tanstack
• Expo：https://www.better-auth.com/docs/integrations/expo

参考资料

• 数据库适配器 — Drizzle、Kysely、Prisma 适配器、Cloudflare Workers 工厂模式
• 会话管理 — Cookie 缓存、无状态会话、存储优先级、freshAge 限制
• 插件和社交身份验证 — 插件设置、OAuth 2.1 提供方、管理员 RBAC、社交提供方权限范围
• 电子邮件和密码 — 验证、密码重置、计时攻击防护、哈希（scrypt、argon2）、令牌安全
• 双重身份验证 — TOTP、电子邮件/SMS OTP、备用代码、受信任设备、2FA 会话流程
• 组织 — 多租户组织、团队、邀请、RBAC、动态访问控制、生命周期钩子
• 配置 — 用户/账户配置、速率限制、钩子、CSRF、受信任来源、Cookie/OAuth 安全、生产环境检查清单
• 框架集成 — TanStack Start 设置、Expo/React Native、客户端导入、类型安全
• 迁移指南 — 使用架构映射和会话策略，从 NextAuth/Auth.js、Clerk 或 Supabase Auth 迁移
• 故障排除 — D1 一致性、CORS、OAuth 重定向、管理员 403、nanostore 刷新、已知问题