tool-better-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Better Auth Integration Guide

Better Auth 集成指南

Always consult better-auth.com/docs for code examples and latest API.

Better Auth is a TypeScript-first, framework-agnostic auth framework supporting email/password, OAuth, magic links, passkeys, and more via plugins.

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

Better Auth是一个优先支持TypeScript的、与框架无关的认证框架，通过插件支持邮箱/密码、OAuth、魔法链接、通行密钥等多种认证方式。

Quick Reference

快速参考

Environment Variables

环境变量

```
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.

```
BETTER_AUTH_SECRET
```
- 加密密钥（至少32个字符）。生成方式：
```
openssl rand -base64 32
```
```
BETTER_AUTH_URL
```
- 基础URL（例如：
```
https://example.com
```
）

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

baseURL

secret

。

File Location

文件位置

CLI looks for

auth.ts

in:

./

./lib

./utils

, or under

./src

. Use

--config

for custom path.

CLI会在以下目录中查找

auth.ts

：

./

、

./lib

、

./utils

或

./src

下。使用

--config

指定自定义路径。

CLI Commands

CLI命令

```
npx @better-auth/cli@latest migrate
```
- Apply schema (built-in adapter)
```
npx @better-auth/cli@latest generate
```
- Generate schema for Prisma/Drizzle
```
npx @better-auth/cli mcp --cursor
```
- Add MCP to AI tools

Re-run after adding/changing plugins.

```
npx @better-auth/cli@latest migrate
```
- 应用数据库 schema（内置适配器）
```
npx @better-auth/cli@latest generate
```
- 为Prisma/Drizzle生成schema
```
npx @better-auth/cli mcp --cursor
```
- 为AI工具添加MCP

添加或修改插件后请重新运行上述命令。

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 for most features. See adapters docs.
`secondaryStorage`	Redis/KV for sessions & 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`	大多数功能都需要配置。请查看适配器文档。
`secondaryStorage`	用于会话和速率限制的Redis/KV存储
`emailAndPassword`	设置 `{ enabled: true }` 以启用邮箱/密码认证
`socialProviders`	配置格式： `{ google: { clientId, clientSecret }, ... }`
`plugins`	插件数组
`trustedOrigins`	CSRF白名单

Database

数据库

Direct connections: Pass

pg.Pool

mysql2

pool,

better-sqlite3

, or

bun:sqlite

instance.

ORM adapters: Import from

better-auth/adapters/drizzle

better-auth/adapters/prisma

better-auth/adapters/mongodb

Critical: Better Auth uses adapter model names, NOT underlying table names. If Prisma model is

User

mapping to table

users

, use

modelName: "user"

(Prisma reference), not

"users"

直接连接： 传入

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"

。

Session Management

会话管理

Storage priority:

If
```
secondaryStorage
```
defined → sessions go there (not DB)
Set
```
session.storeSessionInDatabase: true
```
to also persist to DB
No database +
```
cookieCache
```
→ fully stateless mode

Cookie cache strategies:

```
compact
```
(default) - Base64url + HMAC. Smallest.
```
jwt
```
- Standard JWT. Readable but signed.
```
jwe
```
- Encrypted. Maximum security.

Key options:

session.expiresIn

(default 7 days),

session.updateAge

(refresh interval),

session.cookieCache.maxAge

session.cookieCache.version

(change to invalidate all sessions).

存储优先级：

如果定义了
```
secondaryStorage
```
→ 会话将存储在此处（而非数据库）
设置
```
session.storeSessionInDatabase: true
```
可同时将会话持久化到数据库
无数据库 +
```
cookieCache
```
→ 完全无状态模式

Cookie缓存策略：

```
compact
```
（默认）- Base64url + HMAC。体积最小。
```
jwt
```
- 标准JWT。可读但已签名。
```
jwe
```
- 加密格式。安全性最高。

关键选项：

session.expiresIn

（默认7天）、

session.updateAge

（刷新间隔）、

session.cookieCache.maxAge

、

session.cookieCache.version

（修改此值可使所有会话失效）。

User & Account Config

用户与账户配置

User:

user.modelName

user.fields

(column mapping),

user.additionalFields

user.changeEmail.enabled

(disabled by default),

user.deleteUser.enabled

(disabled by default).

Account:

account.modelName

account.accountLinking.enabled

account.storeAccountCookie

(for stateless OAuth).

Required for registration:

email

and

name

fields.

用户：

user.modelName

、

user.fields

（列映射）、

user.additionalFields

、

user.changeEmail.enabled

（默认禁用）、

user.deleteUser.enabled

（默认禁用）。

账户：

account.modelName

、

account.accountLinking.enabled

、

account.storeAccountCookie

（用于无状态OAuth）。

注册必填字段：

email

和

name

字段。

Email Flows

邮箱流程

```
emailVerification.sendVerificationEmail
```
- Must be defined for verification to work

emailVerification.sendOnSignUp

sendOnSignIn

- Auto-send triggers

```
emailAndPassword.sendResetPassword
```
- Password reset email handler

```
emailVerification.sendVerificationEmail
```
- 必须定义此配置才能启用邮箱验证功能

emailVerification.sendOnSignUp

sendOnSignIn

- 自动发送验证邮件的触发条件

```
emailAndPassword.sendResetPassword
```
- 密码重置邮件处理函数

Security

安全

In
advanced
:

```
useSecureCookies
```
- Force HTTPS cookies
```
disableCSRFCheck
```
- ⚠️ Security risk
```
disableOriginCheck
```
- ⚠️ Security risk
```
crossSubDomainCookies.enabled
```
- Share cookies across subdomains
```
ipAddress.ipAddressHeaders
```
- Custom IP headers for proxies
```
database.generateId
```
- Custom ID generation or
```
"serial"
```
/
```
"uuid"
```
/
```
false
```

Rate limiting:

rateLimit.enabled

rateLimit.window

rateLimit.max

rateLimit.storage

("memory" | "database" | "secondary-storage").

在
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

钩子

Endpoint hooks:

hooks.before

hooks.after

- Array of

{ matcher, handler }

. Use

createAuthMiddleware

. Access

ctx.path

ctx.context.returned

(after),

ctx.context.session

Database hooks:

databaseHooks.user.create.before/after

, same for

session

account

. Useful for adding default values or post-creation actions.

Hook context (
ctx.context
):

session

secret

authCookies

password.hash()

verify()

adapter

internalAdapter

generateId()

tables

baseURL

端点钩子：

hooks.before

hooks.after

- 由

{ matcher, handler }

组成的数组。使用

createAuthMiddleware

。可访问

ctx.path

、

ctx.context.returned

（after钩子中）、

ctx.context.session

。

数据库钩子：

databaseHooks.user.create.before/after

，会话和账户也有类似钩子。可用于添加默认值或执行创建后的操作。

钩子上下文(
ctx.context
)：

session

、

secret

、

authCookies

、

password.hash()

verify()

、

adapter

、

internalAdapter

、

generateId()

、

tables

、

baseURL

。

Plugins

插件

Import from dedicated paths for tree-shaking:

import { twoFactor } from "better-auth/plugins/two-factor"

NOT

from "better-auth/plugins"

Popular plugins:

twoFactor

organization

passkey

magicLink

emailOtp

username

phoneNumber

admin

apiKey

bearer

jwt

multiSession

sso

oauthProvider

oidcProvider

openAPI

genericOAuth

Client plugins go in

createAuthClient({ plugins: [...] })

从专用路径导入以实现摇树优化：

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: [...] })

中。

Client

客户端

Import from:

better-auth/client

(vanilla),

better-auth/react

better-auth/vue

better-auth/svelte

better-auth/solid

Key methods:

signUp.email()

signIn.email()

signIn.social()

signOut()

useSession()

getSession()

revokeSession()

revokeSessions()

从以下路径导入：

better-auth/client

（原生JS）、

better-auth/react

、

better-auth/vue

、

better-auth/svelte

、

better-auth/solid

。

核心方法：

signUp.email()

、

signIn.email()

、

signIn.social()

、

signOut()

、

useSession()

、

getSession()

、

revokeSession()

、

revokeSessions()

。

Type Safety

类型安全

Infer types:

typeof auth.$Infer.Session

typeof auth.$Infer.Session.user

For separate client/server projects:

createAuthClient<typeof auth>()

推导类型：

typeof auth.$Infer.Session

、

typeof auth.$Infer.Session.user

。

对于分离的客户端/服务端项目：

createAuthClient<typeof auth>()

。

Common Gotchas

常见误区

Model vs table name - Config uses ORM model name, not DB table name
Plugin schema - Re-run CLI after adding plugins
Secondary storage - Sessions go there by default, not DB
Cookie cache - Custom session fields NOT cached, always re-fetched
Stateless mode - No DB = session in cookie only, logout on cache expiry
Change email flow - Sends to current email first, then new email

模型名 vs 表名 - 配置中使用的是ORM模型名，而非数据库表名
插件Schema - 添加插件后请重新运行CLI命令
二级存储 - 会话默认存储在二级存储中，而非数据库
Cookie缓存 - 自定义会话字段不会被缓存，需始终重新获取
无状态模式 - 无数据库时，会话仅存储在Cookie中，缓存过期后自动登出
修改邮箱流程 - 会先发送邮件到当前邮箱，再发送到新邮箱