Better Auth 集成指南

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

安装工作流

1. 安装依赖: npm install better-auth
2. 设置环境变量: BETTER_AUTH_SECRET 和 BETTER_AUTH_URL
3. 创建包含数据库和配置的 auth.ts 文件
4. 为你的框架创建路由处理器
5. 运行迁移: npx @better-auth/cli@latest migrate
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 @better-auth/cli@latest migrate – 应用数据库 Schema (内置适配器)
• npx @better-auth/cli@latest generate – 为 Prisma/Drizzle 生成 Schema
• npx @better-auth/cli mcp --cursor – 将 MCP 添加到 AI 工具中

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

核心配置选项

数据库

直接连接: 传递 pg.Pool, mysql2 连接池, better-sqlite3, 或 bun:sqlite 实例。

ORM 适配器: 从 better-auth/adapters/drizzle, better-auth/adapters/prisma, better-auth/adapters/mongodb 导入。

重要: Better Auth 使用适配器的模型名称 (Model Name)，而非底层的数据库表名 (Table Name)。如果 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): user.modelName, user.fields (字段映射), user.additionalFields, user.changeEmail.enabled (默认禁用), user.deleteUser.enabled (默认禁用)。

账户 (Account): 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)

端点钩子: 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>()。

常见陷阱 (Common Gotchas)

1. 模型名与表名 – 配置使用 ORM 模型名，而非数据库表名
2. 插件 Schema – 添加插件后请重新运行 CLI 命令
3. 二级存储 – 会话默认存储在那里，而非数据库
4. Cookie 缓存 – 自定义会话字段不会被缓存，总是重新获取
5. 无状态模式 – 无数据库 = 会话仅在 Cookie 中，缓存过期即退出登录
6. 更改邮箱流程 – 会先发送到当前邮箱，然后发送到新邮箱

资源

• 文档
• 选项参考
• LLMs.txt
• GitHub 仓库
• 初始化选项源码