better-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

better-auth

Package: better-auth@1.4.15 (ESM-only since v1.4.0) Docs: https://better-auth.com/docs | GitHub: https://github.com/better-auth/better-auth

包: better-auth@1.4.15（自v1.4.0起仅支持ESM）文档: https://better-auth.com/docs | GitHub: https://github.com/better-auth/better-auth

Environment Setup

环境配置

Variable	Purpose
`BETTER_AUTH_SECRET`	Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
`BETTER_AUTH_URL`	Base URL (e.g., `https://example.com` )

Only define

baseURL

secret

in config if env vars are NOT set. CLI looks for

auth.ts

in:

./

./lib

./utils

, or

./src

环境变量	用途
`BETTER_AUTH_SECRET`	加密密钥（至少32字符）。生成命令： `openssl rand -base64 32`
`BETTER_AUTH_URL`	基础URL（例如： `https://example.com` ）

仅当未设置环境变量时，才在配置中定义

baseURL

secret

。CLI会在以下路径查找

auth.ts

：

./

、

./lib

、

./utils

或

./src

。

Core Config Options

核心配置选项

Option	Notes
`appName`	Optional display name
`baseURL`	Only if `BETTER_AUTH_URL` not set
`basePath`	Default `/api/auth` . Set `/` for root.
`secret`	Only if `BETTER_AUTH_SECRET` not set
`database`	Required unless using stateless mode (v1.4+)
`secondaryStorage`	Redis/KV for sessions and rate limits
`emailAndPassword`	`{ enabled: true }` to activate
`socialProviders`	`{ google: { clientId, clientSecret }, ... }`
`plugins`	Array of plugins
`trustedOrigins`	CSRF whitelist

选项	说明
`appName`	可选的显示名称
`baseURL`	仅当未设置 `BETTER_AUTH_URL` 时配置
`basePath`	默认值为 `/api/auth` 。设置为 `/` 可映射到根路径。
`secret`	仅当未设置 `BETTER_AUTH_SECRET` 时配置
`database`	除非使用无状态模式（v1.4+），否则为必填项
`secondaryStorage`	用于会话和速率限制的Redis/KV存储
`emailAndPassword`	设置 `{ enabled: true }` 以启用账号密码登录
`socialProviders`	示例： `{ google: { clientId, clientSecret }, ... }`
`plugins`	插件数组
`trustedOrigins`	CSRF白名单

Plugin Reference

插件参考

Plugin	Description
twoFactor	TOTP, email OTP, backup codes
organization	Multi-tenant orgs, teams, invitations, RBAC
admin	User management, impersonation, banning
passkey	WebAuthn passwordless login
magicLink	Email-based passwordless login
jwt	JWT tokens with key rotation, JWKS
oauthProvider	Build your own OAuth 2.1 provider (separate `@better-auth/oauth-provider` package)
sso	Enterprise SSO with OIDC, OAuth2, SAML 2.0 (separate `@better-auth/sso` package)
scim	Enterprise user provisioning (separate `@better-auth/scim` package)
stripe	Payment and subscription management
bearer	API token auth for mobile/CLI
apiKey	Token-based auth with rate limits
oneTap	Google One Tap frictionless sign-in
anonymous	Guest user access without PII
genericOAuth	Custom OAuth providers with PKCE
emailOTP	Email-based one-time password auth
phoneNumber	Phone/SMS-based OTP sign-in
username	Username-based sign-in (alternative to email)
multiSession	Multiple accounts in same browser
openAPI	Interactive API docs at `/api/auth/reference`

插件	描述
twoFactor	支持TOTP、邮箱OTP、备份码的双因素认证
organization	多租户组织、团队、邀请、RBAC管理
admin	用户管理、身份模拟、账号封禁功能
passkey	基于WebAuthn的无密码登录
magicLink	基于邮箱的无密码登录
jwt	支持密钥轮换、JWKS的JWT令牌
oauthProvider	构建自定义OAuth 2.1提供商（需单独安装 `@better-auth/oauth-provider` 包）
sso	企业级SSO（支持OIDC、OAuth2、SAML 2.0，需单独安装 `@better-auth/sso` 包）
scim	企业级用户配置（需单独安装 `@better-auth/scim` 包）
stripe	支付与订阅管理
bearer	适用于移动端/CLI的API令牌认证
apiKey	带速率限制的令牌式认证
oneTap	Google一键式无感登录
anonymous	无需个人身份信息的访客用户访问
genericOAuth	支持PKCE的自定义OAuth提供商
emailOTP	基于邮箱的一次性密码认证
phoneNumber	基于手机号/SMS的OTP登录
username	基于用户名的登录（替代邮箱登录）
multiSession	同一浏览器中多账号登录
openAPI	在 `/api/auth/reference` 提供交互式API文档

Session Strategies

会话策略

Strategy	Format	Use Case
Compact (default)	Base64url + HMAC-SHA256	Smallest, fastest
JWT	Standard JWT	Interoperable
JWE	A256CBC-HS512 encrypted	Most secure

策略	格式	适用场景
Compact（默认）	Base64url + HMAC-SHA256	体积最小、速度最快
JWT	标准JWT格式	跨系统互操作性强
JWE	A256CBC-HS512加密格式	安全性最高

Getting Started

快速开始

For new projects or first-time Better Auth setup, use the official interactive setup skill:

bash

npx skills add better-auth/skills -s create-auth-skill

This walks through framework detection, database selection, auth method choices, plugin setup, and generates the initial configuration.

对于新项目或首次配置Better Auth，使用官方交互式安装工具：

bash

npx skills add better-auth/skills -s create-auth-skill

该工具会自动检测框架、选择数据库、配置认证方式、设置插件，并生成初始配置文件。

Anti-Patterns

反模式

Anti-Pattern	Correct Approach
Using `d1Adapter`	Use Drizzle or Kysely adapter with `provider: "sqlite"`
Using table name in config	Use ORM model name, not DB table name
Forgetting CLI after plugin changes	Re-run `npx @better-auth/cli@latest generate`
`tanstackStartCookies()` not last plugin	Must be the last plugin in array (TanStack Start)
Checking `session` for login state	Check `session?.user` — session object is always truthy
Missing `nodejs_compat` flag	Required in `wrangler.toml` for Cloudflare Workers
Kysely CamelCasePlugin with auth	Use separate Kysely instance without the plugin
Using old `reactStartCookies` import	Renamed to `tanstackStartCookies` from `better-auth/tanstack-start` in v1.4.14

反模式	正确做法
使用 `d1Adapter`	使用Drizzle或Kysely适配器并设置 `provider: "sqlite"`
在配置中使用数据库表名	使用ORM模型名称，而非数据库表名
添加或修改插件后未重新运行CLI	重新运行 `npx @better-auth/cli@latest generate`
`tanstackStartCookies()` 不是最后一个插件	在TanStack Start中必须将其作为数组最后一个插件
检查 `session` 判断登录状态	检查 `session?.user` —— session对象始终为真
缺失 `nodejs_compat` 标志	在Cloudflare Workers的 `wrangler.toml` 中为必填项
Kysely CamelCasePlugin与认证一起使用	使用不带该插件的独立Kysely实例
使用旧的 `reactStartCookies` 导入	自v1.4.14起已重命名为 `tanstackStartCookies` ，需从 `better-auth/tanstack-start` 导入

Common Mistakes

常见错误

Mistake	Correct Pattern
Setting `baseURL` and `secret` in config when env vars are already set	Only define these in config if `BETTER_AUTH_URL` and `BETTER_AUTH_SECRET` env vars are NOT set
Using CommonJS require syntax with better-auth v1.4+	better-auth is ESM-only since v1.4.0; use `import` syntax exclusively
Not re-running CLI generate after adding or changing plugins	Always run `npx @better-auth/cli@latest generate` after plugin changes to update DB schema
Checking `session` object truthy state for login detection	Check `session?.user` instead; the session object itself is always truthy
Using `d1Adapter` directly for Cloudflare D1	Use Drizzle or Kysely adapter with `provider: "sqlite"` for D1 compatibility

错误	正确做法
已设置环境变量仍在配置中定义 `baseURL` 和 `secret`	仅当未设置 `BETTER_AUTH_URL` 和 `BETTER_AUTH_SECRET` 环境变量时，才在配置中定义这两个参数
在better-auth v1.4+中使用CommonJS的require语法	better-auth自v1.4.0起仅支持ESM；请仅使用 `import` 语法
添加或修改插件后未重新运行CLI生成命令	添加或修改插件后，务必运行 `npx @better-auth/cli@latest generate` 以更新数据库架构
通过 `session` 对象是否为真判断登录状态	应检查 `session?.user` ；session对象本身始终为真
直接为Cloudflare D1使用 `d1Adapter`	使用Drizzle或Kysely适配器并设置 `provider: "sqlite"` 以兼容D1

Breaking Changes

破坏性变更

Version	Change
v1.4.14	`reactStartCookies` renamed to `tanstackStartCookies` (import from `better-auth/tanstack-start` )
v1.4.6	`allowImpersonatingAdmins` defaults to `false`
v1.4.0	ESM-only (no CommonJS); SSO, SCIM, OAuth Provider moved to separate packages
v1.3.0	Multi-team table structure: new `teamMembers` table needed

版本	变更内容
v1.4.14	`reactStartCookies` 重命名为 `tanstackStartCookies` （需从 `better-auth/tanstack-start` 导入）
v1.4.6	`allowImpersonatingAdmins` 默认值改为 `false`
v1.4.0	仅支持ESM（不再支持CommonJS）；SSO、SCIM、OAuth Provider移至单独包中
v1.3.0	多团队表结构变更：新增 `teamMembers` 表

Delegation

职责划分

When working on auth, delegate to:

```
application-security
```
— Security architecture and threat modeling
```
database
```
— Drizzle ORM schema and migrations
```
tanstack-start
```
— TanStack Start integration patterns

处理认证相关工作时，可分工给：

```
application-security
```
—— 安全架构与威胁建模
```
database
```
—— Drizzle ORM架构与迁移
```
tanstack-start
```
—— TanStack Start集成方案

Resources

资源

Docs: https://better-auth.com/docs
Options Reference: https://better-auth.com/docs/reference/options
LLMs.txt: https://better-auth.com/llms.txt
Changelog: https://www.better-auth.com/changelogs
TanStack Start: https://www.better-auth.com/docs/integrations/tanstack
Expo: https://www.better-auth.com/docs/integrations/expo

文档: https://better-auth.com/docs
选项参考: https://better-auth.com/docs/reference/options
LLMs.txt: https://better-auth.com/llms.txt
更新日志: https://www.better-auth.com/changelogs
TanStack Start集成: https://www.better-auth.com/docs/integrations/tanstack
Expo集成: https://www.better-auth.com/docs/integrations/expo

References

参考文档

Database Adapters — Drizzle, Kysely, Prisma adapters, Cloudflare Workers factory pattern
Session Management — Cookie cache, stateless sessions, storage priority, freshAge constraints
Plugins and Social Auth — Plugin setup, OAuth 2.1 provider, admin RBAC, social provider scopes
Email and Password — Verification, password reset, timing attack prevention, hashing (scrypt, argon2), token security
Two-Factor Authentication — TOTP, email/SMS OTP, backup codes, trusted devices, 2FA session flow
Organizations — Multi-tenant orgs, teams, invitations, RBAC, dynamic access control, lifecycle hooks
Configuration — User/account config, rate limiting, hooks, CSRF, trusted origins, cookie/OAuth security, production checklist
Framework Integration — TanStack Start setup, Expo/React Native, client imports, type safety
Migration Guides — Migrate from NextAuth/Auth.js, Clerk, or Supabase Auth with schema mappings and session strategies
Troubleshooting — D1 consistency, CORS, OAuth redirect, admin 403, nanostore refresh, known bugs

数据库适配器 —— Drizzle、Kysely、Prisma适配器，Cloudflare Workers工厂模式
会话管理 —— Cookie缓存、无状态会话、存储优先级、freshAge约束
插件与社交认证 —— 插件配置、OAuth 2.1提供商、管理员RBAC、社交提供商权限范围
邮箱与密码登录 —— 验证流程、密码重置、时序攻击防护、哈希算法（scrypt、argon2）、令牌安全
双因素认证 —— TOTP、邮箱/SMS OTP、备份码、可信设备、2FA会话流程
组织管理 —— 多租户组织、团队、邀请、RBAC、动态访问控制、生命周期钩子
配置指南 —— 用户/账号配置、速率限制、钩子、CSRF、可信来源、Cookie/OAuth安全、生产环境检查清单
框架集成 —— TanStack Start配置、Expo/React Native、客户端导入、类型安全
迁移指南 —— 从NextAuth/Auth.js、Clerk、Supabase Auth迁移的架构映射与会话策略
故障排查 —— D1一致性、CORS、OAuth重定向、管理员403错误、nanostore刷新、已知问题