一、用途 Better Auth 是一个以 TypeScript 为先、框架无关的认证框架,支持邮箱密码、OAuth、魔法链接、Passkey 等,并通过插件扩展能力。本技能面向需要在项目中集成 Better Auth 的场景,官方建议始终查阅 better-auth.com/docs 获取代码示例与最新 API。
二、环境变量与文件位置 环境变量包括 BETTER_AUTH_SECRET(加密密钥,至少 32 个字符,可用 openssl rand -base64 32 生成)与 BETTER_AUTH_URL(基础 URL,如 https://example.com)。只有在未设置环境变量时,才需要在配置中定义 baseURL/secret。CLI 会在 ./、./lib、./utils 或 ./src 下查找 auth.ts,也可用 --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 连接池、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>()。
十三、常见注意事项 模型名与表名不同,配置使用 ORM 模型名而非数据库表名;添加插件后需重新运行 CLI 生成 schema;使用 secondaryStorage 时会话默认存于其中而非数据库;Cookie 缓存不会缓存自定义会话字段,始终重新获取;无状态模式(无数据库)仅将会话存于 Cookie,缓存过期即登出;修改邮箱流程会先发送到当前邮箱,再发送到新邮箱。
十四、资源 文档、Options Reference、LLMs.txt、GitHub、Init Options Source。