better-auth-best-practices

用途

本技能用于在开发中集成 Better Auth——一个 TypeScript 优先、框架无关的认证框架。当处理 better-auth 或认证相关代码时可参考本技能。官方建议始终查阅 better-auth.com/docs 获取代码示例与最新 API。

主要能力

Better Auth 支持邮箱密码、OAuth、魔法链接、Passkey 等认证方式，并可通过插件扩展。

环境变量

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

仅当环境变量未设置时，才在配置中定义 baseURL/secret。

文件位置

CLI 会在以下位置查找 auth.ts：./、./lib、./utils 或 ./src 下。可用 --config 指定自定义路径。

CLI 命令

npx @better-auth/cli@latest migrate：应用 schema（内置适配器）
npx @better-auth/cli@latest generate：为 Prisma/Drizzle 生成 schema
npx @better-auth/cli mcp --cursor：将 MCP 添加到 AI 工具

添加或更改插件后需重新运行。

核心配置项

appName：可选显示名称
baseURL：仅当未设置 BETTER_AUTH_URL 时使用
basePath：默认 /api/auth，设为 / 表示根路径
secret：仅当未设置 BETTER_AUTH_SECRET 时使用
database：多数功能必需，参见适配器文档
secondaryStorage：用于会话与限流的 Redis/KV
emailAndPassword：{ enabled: true } 启用
socialProviders：{ google: { clientId, clientSecret }, ... }
plugins：插件数组
trustedOrigins：CSRF 白名单

数据库

直接连接：传入 pg.Pool、mysql2 pool、better-sqlite3 或 bun:sqlite 实例。
ORM 适配器：从 better-auth/adapters/drizzle、better-auth/adapters/prisma、better-auth/adapters/mongodb 导入。
关键点：Better Auth 使用适配器模型名，而非底层表名。若 Prisma 模型为 User 映射到表 users，应使用 modelName: "user"（Prisma 引用），而非 "users"。

会话管理

存储优先级：

若定义了 secondaryStorage，会话存于其中（不存数据库）
设置 session.storeSessionInDatabase: true 可同时持久化到数据库
无数据库 + cookieCache 时为完全无状态模式

Cookie 缓存策略：

compact（默认）：Base64url + HMAC，体积最小
jwt：标准 JWT，可读但已签名
jwe：加密，安全性最高

关键选项：session.expiresIn（默认 7 天）、session.updateAge（刷新间隔）、session.cookieCache.maxAge、session.cookieCache.version（更改可使所有会话失效）。

用户与账户配置

用户：user.modelName、user.fields（列映射）、user.additionalFields、user.changeEmail.enabled（默认禁用）、user.deleteUser.enabled（默认禁用）。
账户：account.modelName、account.accountLinking.enabled、account.storeAccountCookie（用于无状态 OAuth）。
注册必需字段：email 和 name。

邮件流程

emailVerification.sendVerificationEmail：必须定义才能启用验证
emailVerification.sendOnSignUp / sendOnSignIn：自动发送触发
emailAndPassword.sendResetPassword：密码重置邮件处理器

安全

在 advanced 中：

useSecureCookies：强制 HTTPS cookie
disableCSRFCheck：⚠️ 安全风险
disableOriginCheck：⚠️ 安全风险
crossSubDomainCookies.enabled：跨子域共享 cookie
ipAddress.ipAddressHeaders：代理的自定义 IP 头
database.generateId：自定义 ID 生成或 "serial"/"uuid"/false

限流：rateLimit.enabled、rateLimit.window、rateLimit.max、rateLimit.storage（"memory" | "database" | "secondary-storage"）。

钩子

端点钩子：hooks.before / hooks.after，为 { matcher, handler } 数组。使用 createAuthMiddleware。可访问 ctx.path、ctx.context.returned（after）、ctx.context.session。
数据库钩子：databaseHooks.user.create.before/after，session、account 同理。用于添加默认值或创建后操作。
钩子上下文（ctx.context）：session、secret、authCookies、password.hash()/verify()、adapter、internalAdapter、generateId()、tables、baseURL。

插件

从专用路径导入以支持 tree-shaking： import { twoFactor } from "better-auth/plugins/two-factor" 而非从 "better-auth/plugins" 导入。

常用插件：twoFactor、organization、passkey、magicLink、emailOtp、username、phoneNumber、admin、apiKey、bearer、jwt、multiSession、sso、oauthProvider、oidcProvider、openAPI、genericOAuth。

客户端插件放在 createAuthClient({ plugins: [...] }) 中。

客户端

导入来源：better-auth/client（vanilla）、better-auth/react、better-auth/vue、better-auth/svelte、better-auth/solid。

关键方法：signUp.email()、signIn.email()、signIn.social()、signOut()、useSession()、getSession()、revokeSession()、revokeSessions()。

类型安全

推断类型：typeof auth.$Infer.Session、typeof auth.$Infer.Session.user。

对于客户端/服务端分离项目：createAuthClient<typeof auth>()。

常见注意事项

模型名 vs 表名：配置使用 ORM 模型名，而非数据库表名
插件 schema：添加插件后需重新运行 CLI
二级存储：会话默认存于其中，而非数据库
Cookie 缓存：自定义会话字段不会被缓存，始终重新获取
无状态模式：无数据库 = 会话仅在 cookie 中，缓存过期即登出
更改邮箱流程：先发送到当前邮箱，再发送到新邮箱

使用方式

在集成 Better Auth 时，按上述配置项、CLI 命令与插件机制进行设置。官方建议始终查阅 better-auth.com/docs 获取代码示例与最新 API。

适用场景

适用于需要在 TypeScript 项目中集成认证功能的开发场景，包括邮箱密码、OAuth、魔法链接、Passkey 等登录方式，以及会话管理、限流、插件扩展等需求。

限制

本技能为集成参考指南，具体代码示例与最新 API 需查阅官方文档。部分配置项（如 disableCSRFCheck、disableOriginCheck）存在安全风险，需谨慎使用。