better-auth

Better Auth 最佳实践

Better Auth 的实现与迁移指南。Better Auth 是一个与框架无关的 TypeScript 身份验证与授权库。本指南包含 42 条规则，按影响程度划分为 8 个类别，内容源自官方文档和迁移指南。

适用场景

以下情况请参考这些指南：

• 设置新的 Better Auth 实例（配置、适配器、路由处理程序、客户端）
• 接入特定框架的集成（Next.js App/Pages Router、SvelteKit、Hono、Express、Nuxt、Astro）
• 配置会话、Cookie 和安全性（速率限制、受信任的来源、密码哈希）
• 添加插件：2FA、organization、admin、magicLink、JWT、passkey、multi-session
• 从其他身份验证库迁移（NextAuth/Auth.js、Clerk、Auth0、Supabase Auth）
• 调试“session is null” / “redirect_uri_mismatch” / 403 CSRF 错误
• 审查涉及 lib/auth.ts、auth-client.ts 或 /api/auth/ 路由处理程序的 PR

按优先级划分的规则类别

优先级	类别	影响	前缀
1	设置与配置	CRITICAL	setup-
2	数据库适配器与架构	CRITICAL	db-
3	API 路由处理程序	CRITICAL	route-
4	会话与 Cookie	HIGH	session-
5	身份验证方法与提供方	HIGH	auth-
6	安全与加固	HIGH	security-
7	插件与扩展	MEDIUM	plugins-
8	从其他身份验证库迁移	MEDIUM	migrate-

快速参考

1. 设置与配置（CRITICAL）

• setup-secret — 为每个环境设置强 BETTER_AUTH_SECRET
• setup-base-url — 为每个环境配置明确的 baseURL
• setup-client-base-url — 使客户端 baseURL 与服务端一致
• setup-singleton — 从仅服务端模块导出单个身份验证实例
• setup-trusted-origins — 为所有非 baseURL 调用方配置 trustedOrigins

2. 数据库适配器与架构（CRITICAL）

• db-adapter-selection — 选择与 ORM 匹配的适配器
• db-schema-generate — 每次部署前运行 auth generate，然后执行 ORM 迁移
• db-additional-fields — 通过 additionalFields 扩展用户架构
• db-plugin-schema-customization — 通过 schema 选项重命名插件表
• db-database-hooks — 使用 databaseHooks 实现跨领域逻辑
• db-connection-pooling — 与应用的其他部分共享一个池化 DB 客户端

3. API 路由处理程序（CRITICAL）

• route-mount-catchall — 在 /api/auth/[...all] 挂载 catch-all 处理程序
• route-runtime-selection — 对调用 auth.api 的中间件使用 Node.js 运行时
• route-no-body-consumers — 在任何解析请求体的中间件之前挂载身份验证

4. 会话与 Cookie（HIGH）

• session-server-vs-client — 服务端使用 auth.api.getSession，客户端使用 authClient.useSession
• session-expiry-tuning — 同时配置 expiresIn 和 updateAge
• session-cookie-cache — 启用 cookieCache，减少会话数据库查询
• session-cookie-attributes — 为跨站流程设置 sameSite、secure、partitioned
• session-cross-subdomain — 为多子域名应用启用 crossSubDomainCookies
• session-customsession-fields — 使用 customSession 添加计算字段

5. 身份验证方法与提供商（HIGH）

• auth-require-email-verification — 启用 requireEmailVerification，并配置 sendVerificationEmail
• auth-oauth-redirect-uri — 确保 OAuth redirectURI 与提供商控制台中的值完全一致
• auth-oauth-env-vars — 从环境变量加载 OAuth 凭据，切勿内联填写
• auth-magic-link-setup — 启用 magicLink 插件前，先实现 sendMagicLink
• auth-client-sign-in-helpers — 使用带有 callbackURL 的 authClient.signIn.social
• auth-infer-additional-fields — 在客户端添加 inferAdditionalFields，以同步类型

6. 安全与加固（HIGH）

• security-rate-limit — 在生产环境中启用 rateLimit，并使用持久化存储
• security-password-hash-interop — 从 bcrypt/argon2 迁移时，覆盖哈希函数
• security-revoke-on-password-reset — 启用 revokeSessionsOnPasswordReset
• security-min-password-length — 将 minPasswordLength 设为至少 10
• security-trusted-origins-strict — 切勿对 trustedOrigins 使用通配符

7. 插件与扩展（MEDIUM）

• plugins-next-cookies-last — 在 Next.js 中将 nextCookies() 放在最后一个插件位置
• plugins-two-factor-issuer — 将 appName 设为 2FA 发行方
• plugins-shared-access-control — 只定义一次 ac 和角色，并在服务端与客户端共享
• plugins-pair-client-server — 为每个服务端插件配对对应的客户端插件
• plugins-organization-active-context — 在会话中设置当前活动组织
• plugins-jwt-when-to-use — 仅在面向外部服务使用者时使用 jwt 插件
• plugins-admin-impersonation — 使用管理员插件的 impersonate 方法获取支持访问权限

8. 从其他身份验证方案迁移（MEDIUM）

• migrate-parallel-cutover — 切换期间，让 Better Auth 与旧身份验证方案并行运行
• migrate-oauth-account-mapping — 将旧 OAuth 身份映射到 account 行
• migrate-force-allow-id — 使用 forceAllowId 保留现有用户 ID
• migrate-nextauth-schema-mapping — 逐字段映射 NextAuth v5 列

使用方法

对于全新实现，请按以下优先级阅读：先阅读所有 setup- 规则，然后是 db-，最后是 route-——这些 CRITICAL 类别必须正确，否则其他内容都无法正常工作。完成基础配置后，根据你的范围选择相应规则：使用 session- 调整 Cookie/过期时间，使用 auth- 配置提供方，使用 security- 加固生产环境。

如果要从其他身份验证库迁移，请先阅读 migrate-parallel-cutover（策略），然后阅读 security-password-hash-interop（保留用户密码），再阅读 migrate-oauth-account-mapping 和 migrate-nextauth-schema-mapping（数据布局）。

阅读各个参考文件，了解详细说明、错误与正确的代码示例，以及指向 Better Auth 官方文档的链接。

参考文件

文件	描述
references/_sections.md	按影响程度排序的类别定义
assets/templates/_template.md	添加新规则的模板
metadata.json	版本、参考资料和领域元数据