better-auth-best-practices

Better Auth 集成指南

文档版本

请使用与项目中已安装的 Better Auth 版本相匹配的文档。不同的维护版本系列可能使用不同的 API 和插件名称。

1. 优先使用用户明确指定的版本。
2. 否则，检查锁定文件中解析出的 better-auth 版本；如果没有锁定文件，则回退到包清单。
3. 如果可以使用 Better Auth MCP，请调用 get_doc 并传入 /llms.txt，以将该包版本映射到文档标识符。每次调用 search_docs 时都传入该标识符，并将结果路径原样传给 get_doc。
4. 如果没有 MCP，请从 better-auth.com/llms.txt 开始，并查找匹配的版本索引。
5. 只有在无法确定项目版本，或用户明确询问最新版本或升级时，才使用最新文档。

规划升级时，请将当前已安装版本的指导与目标版本的指导分开。

---

设置工作流

1. 安装：npm install better-auth
2. 设置环境变量：BETTER_AUTH_SECRET 和 BETTER_AUTH_URL
3. 创建包含数据库和配置的 auth.ts
4. 为所用框架创建路由处理程序
5. 运行迁移：
   • 内置适配器： npx auth@latest migrate
   • Drizzle： npx auth@latest generate --output src/db/auth-schema.ts，然后运行 npx drizzle-kit push（开发环境）或 npx drizzle-kit generate && npx drizzle-kit migrate（生产环境）
   • Prisma： npx auth@latest generate --output prisma/schema.prisma，然后运行 npx prisma migrate dev
6. 验证：调用 GET /api/auth/ok——应返回 { status: "ok" }

---

快速参考

环境变量

• 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 auth@latest migrate - 应用架构（内置适配器）
• npx auth@latest generate - 为 Prisma/Drizzle 生成架构
• npx auth@latest 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 连接池、better-sqlite3 或 bun:sqlite 实例。对于 Postgres，还支持 postgres（postgres.js）和 @neondatabase/serverless。

**ORM 适配器：**从 better-auth/adapters/drizzle、better-auth/adapters/prisma、better-auth/adapters/mongodb 导入。

Drizzle 提供程序值："pg"（PostgreSQL）、"mysql"（MySQL）、"sqlite"（SQLite）。必须与所用驱动程序匹配。

**重要：**Better Auth 使用适配器模型名称，而非底层表名。如果 Prisma 模型为 User，映射到的表为 users，请使用 modelName: "user"（Prisma 引用），而不是 "users"。

---

会话管理

存储优先级：

1. 如果定义了 secondaryStorage → 会话存储在其中（而非数据库）
2. 设置 session.storeSessionInDatabase: true，也将会话持久化到数据库
3. 没有数据库 + 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"

不要使用 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>()。

---

常见注意事项

1. 模型名称与表名 - 配置使用 ORM 模型名称，而非数据库表名
2. 插件架构 - 添加插件后重新运行 CLI
3. 辅助存储 - 会话默认存储在其中，而非数据库
4. Cookie 缓存 - 自定义会话字段不会缓存，每次都会重新获取
5. 无状态模式 - 没有数据库 = 会话仅存储在 Cookie 中，缓存过期后注销
6. 更改邮箱流程 - 先发送到当前邮箱，再发送到新邮箱
7. Drizzle：数据库未初始化 - drizzleAdapter(db, ...) 需要来自 drizzle() 的 db 实例。有关设置示例（node-postgres、postgres.js、Neon），请参阅 create-auth 技能。
8. Drizzle：缺少 drizzle.config.ts - drizzle-kit 命令需要一个 drizzle.config.ts，指向生成的架构文件和数据库凭据。

---

Resources

• Docs
• Options Reference
• LLMs.txt
• GitHub
• Init Options Source