name: better-auth-best-practices description: 集成 Better Auth 的技能 - 全面的 TypeScript 身份验证框架。

Better Auth 集成指南

始终参考 better-auth.com/docs 获取代码示例和最新 API。

Better Auth 是一个 TypeScript 优先、框架无关的身份验证框架，支持通过插件实现邮件/密码、OAuth、魔法链接、通行密钥等。

快速参考

环境变量

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 - 应用模式（内置适配器）
npx @better-auth/cli@latest generate - 为 Prisma/Drizzle 生成模式
npx @better-auth/cli mcp --cursor - 添加到 AI 工具的 MCP

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

核心配置选项

选项	备注
`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 池、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 cookies
disableCSRFCheck - ⚠️ 安全风险
disableOriginCheck - ⚠️ 安全风险
crossSubDomainCookies.enabled - 跨子域共享 cookies
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（之后）、ctx.context.session。

数据库钩子： databaseHooks.user.create.before/after，对 session、account 相同。用于添加默认值或后创建操作。

钩子上下文（ctx.context）： session、secret、authCookies、password.hash()/verify()、adapter、internalAdapter、generateId()、tables、baseURL。

插件

从专用路径导入以进行树摇优化：

import { twoFactor } from "better-auth/plugins/two-factor"

不要从 from "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（原生）、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 模型名称，而非数据库表名称
插件模式 - 添加插件后重新运行 CLI
二级存储 - 会话默认存储在那里，而非数据库
Cookie 缓存 - 自定义会话字段不缓存，始终重新获取
无状态模式 - 无数据库 = 会话仅存储在 cookie 中，缓存过期时注销
更改邮件流程 - 先发送到当前邮件，然后新邮件

身份验证框架集成技能Skill better-auth-best-practices