better-auth-best-practices
Better Auth 集成指南
代码示例与最新 API 请查阅 better-auth.com/docs。
Better Auth 是 TypeScript 优先、框架无关的鉴权框架，通过插件支持邮箱/密码、OAuth、魔法链接、Passkey 等。
速查
环境变量
BETTER_AUTH_SECRET：加密密钥（至少 32 字符）。生成：openssl rand -base64 32BETTER_AUTH_URL：根 URL（如https://example.com）
仅当未设置环境变量时，在配置中定义 baseURL / secret。
配置文件位置
CLI 在 ./、./lib、./utils 或 ./src 下查找 auth.ts。自定义路径用 --config。
CLI 命令
npx @better-auth/cli@latest migrate— 应用 schema（内置 adapter）npx @better-auth/cli@latest generate— 为 Prisma/Drizzle 生成 schemanpx @better-auth/cli mcp --cursor— 为 AI 工具添加 MCP
新增或修改插件后需重新执行。
核心配置项
| 选项 | 说明 |
|---|---|
appName |
可选显示名称 |
baseURL |
仅当未设置 BETTER_AUTH_URL 时 |
basePath |
默认 /api/auth，设为 / 可放在根路径 |
secret |
仅当未设置 BETTER_AUTH_SECRET 时 |
database |
多数功能必需，见 adapter 文档 |
secondaryStorage |
Redis/KV，用于 session 与限流 |
emailAndPassword |
{ enabled: true } 启用 |
socialProviders |
{ google: { clientId, clientSecret }, ... } |
plugins |
插件数组 |
trustedOrigins |
CSRF 白名单 |
数据库
直连：传入 pg.Pool、mysql2 池、better-sqlite3 或 bun:sqlite 实例。
ORM adapter：从 better-auth/adapters/drizzle、better-auth/adapters/prisma、better-auth/adapters/mongodb 等导入。
注意：Better Auth 使用 adapter 的 model 名，而非表名。若 Prisma model 为 User 对应表 users，用 modelName: "user"（Prisma 引用），而非 "users"。
Session 管理
存储优先级：
- 若配置了
secondaryStorage→ session 存此处（不存 DB） - 设
session.storeSessionInDatabase: true可同时持久化到 DB - 无 DB +
cookieCache→ 纯无状态模式
Cookie 缓存策略：compact（默认）、jwt、jwe。
关键选项：session.expiresIn、session.updateAge、session.cookieCache.maxAge、session.cookieCache.version（变更可令所有 session 失效）。
用户与 Account 配置
User：user.modelName、user.fields、user.additionalFields、user.changeEmail.enabled、user.deleteUser.enabled。
Account：account.modelName、account.accountLinking.enabled、account.storeAccountCookie。
注册必需字段：email 与 name。
邮件流程
emailVerification.sendVerificationEmail— 验证邮件发送，必须定义emailVerification.sendOnSignUp/sendOnSignIn— 自动发送时机emailAndPassword.sendResetPassword— 重置密码邮件
安全
advanced 中：useSecureCookies、disableCSRFCheck（有风险）、disableOriginCheck（有风险）、crossSubDomainCookies.enabled、ipAddress.ipAddressHeaders、database.generateId 等。
限流：rateLimit.enabled、rateLimit.window、rateLimit.max、rateLimit.storage。
Hooks
端点：hooks.before / hooks.after，{ matcher, handler } 数组，可用 createAuthMiddleware。
数据库：databaseHooks.user.create.before/after 等，用于默认值或创建后逻辑。
Hook 上下文：session、secret、adapter、generateId()、baseURL 等。
插件
按路径导入以支持 tree-shaking：
import { twoFactor } from "better-auth/plugins/two-factor"
勿从 "better-auth/plugins" 整体导入。
常用插件：twoFactor、organization、passkey、magicLink、emailOtp、username、admin、apiKey、bearer、jwt、multiSession、sso、openAPI 等。
客户端插件放在 createAuthClient({ plugins: [...] })。
客户端
从 better-auth/client、better-auth/react、better-auth/vue 等导入。
常用方法：signUp.email()、signIn.email()、signIn.social()、signOut()、useSession()、getSession()、revokeSession() 等。
类型安全
推断类型：typeof auth.$Infer.Session、typeof auth.$Infer.Session.user。
前后端分离项目：createAuthClient()。
常见坑
- Model 与表名 — 配置用 ORM model 名，不是表名
- 插件 schema — 增删插件后重跑 CLI
- Secondary storage — 默认 session 存此处而非 DB
- Cookie cache — 自定义 session 字段不缓存，每次重新拉取
- 无状态模式 — 无 DB 时 session 仅存 cookie，缓存过期即登出
- 改邮箱流程 — 先发当前邮箱，再发新邮箱