# 选项 (/docs/reference/options)

Better Auth 配置选项参考。



Better Auth 配置的所有可用选项列表。详见 [Better Auth 选项](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)。

## `appName` [#appname]

你的应用名称。默认值为 `"Better Auth"`。

它会在需要标识应用的场景中作为显示名称使用——例如，用户使用验证器应用（如 Google Authenticator）设置双因素认证时，`appName` 会作为 TOTP 条目中的发行方名称显示。该名称可按插件覆盖（例如 [2FA 插件的 `issuer` 选项](/docs/plugins/2fa#发布者issuer)）。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	appName: "My App",
})
```

## `baseURL` [#baseurl]

Better Auth 的 Base URL。这通常是你的应用服务器托管的根 URL。你可以将其配置为以下任一形式：

* 对于单域名部署：使用静态字符串
* 对于跨多个允许主机的动态按请求解析：使用对象

如果你的 baseURL 字符串中包含路径组件，它将优先于默认路径。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	baseURL: "https://example.com",
})
```

如果未显式设置，系统将检查环境变量 `BETTER_AUTH_URL`。如果该环境变量也未设置，baseURL 将从传入请求中推断。

<Callout type="warn">
  不建议依赖请求推断。出于安全性和稳定性考虑，请在配置中显式设置 `baseURL`，或通过 `BETTER_AUTH_URL` 环境变量进行设置。
</Callout>

### 动态 Base URL [#动态-base-url]

当你的应用可以通过多个域名访问时，例如预览部署、分支环境或多个生产主机，请使用对象形式。Better Auth 会从 `Host` 请求头以及请求 URL 中获取主机，然后根据 `allowedHosts` 对其进行验证，并根据匹配结果构造请求专属的 baseURL。除非你显式设置 `advanced.trustedProxyHeaders: true`，否则会忽略转发的主机和协议请求头。

```ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
	baseURL: {
		allowedHosts: [
			"myapp.com",
			"www.myapp.com",
			"*.vercel.app",
		],
		protocol: "https",
		fallback: "https://myapp.com",
	},
})
```

* `allowedHosts`：接受的主机模式列表。支持精确匹配（`myapp.com`）、通配符（`*.vercel.app`、`preview-*.myapp.com`）和端口通配符（`localhost:*`）。会自动添加到 [`trustedOrigins`](#trustedorigins)（localhost 条目同时添加 `http` 和 `https`）
* `protocol`：用于 URL 构造的协议。`"http"`、`"https"` 或 `"auto"`（默认值）。仅当 `advanced.trustedProxyHeaders` 为 `true` 时，`"auto"` 才会使用 `x-forwarded-proto`，然后依次使用请求 URL、适用于本地回环主机的 HTTP，否则使用 HTTPS。也会影响 cookie 的 `Secure` 标志：`"https"` → 安全，`"http"` → 不安全，`"auto"` 或未设置 → `NODE_ENV === "production"`。可通过 `advanced.useSecureCookies` 覆盖
* `fallback`：当没有可用的请求主机或传入主机不匹配时使用的 URL。未设置时，无法解析或未知的主机会抛出错误。其来源也会添加到 `trustedOrigins`

<Callout type="warn">
  请谨慎使用 `fallback`。它可能会掩盖本应明显失败的部署或代理配置错误。
</Callout>

当启用 `crossSubDomainCookies` 时，cookie 域名会基于解析后的请求主机推导，除非你已显式设置 `domain`。

有关部署模式和端到端示例，请参阅 [动态 Base URL 指南](/docs/guides/dynamic-base-url)。

## `basePath` [#basepath]

Better Auth 的基础路径。通常是挂载 Better Auth 路由的路径。如果 `baseURL` 中有路径组件，将会覆盖此项。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	basePath: "/api/auth",
})
```

默认值: `/api/auth`

## `trustedOrigins` [#trustedorigins]

默认情况下，Better Auth 会信任你应用的基础 URL（即 [`baseURL`](#baseurl)）。你可以通过此选项指定额外的可信来源。其值可以是静态来源数组、动态返回来源的函数，或用于匹配多个域名的通配符模式。

### 静态来源 [#静态来源]

你可以提供静态数组：

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	trustedOrigins: ["http://localhost:3000", "https://example.com"],
})
```

### 动态来源 [#动态来源]

也可以提供一个根据请求动态返回来源的函数：

```ts
export const auth = betterAuth({
	trustedOrigins: async (request) => {
		// 在初始化和调用 auth.api 时，request 为 undefined
		if (!request) {
			return ["https://my-frontend.com"];
		}
		// 根据请求的动态逻辑
		return ["https://dynamic-origin.com"];
	}
})
```

<Callout type="info">
  `request` 参数在初始化和直接调用 `auth.api` 时为 `undefined`。请确保处理此情况并返回默认可信来源。
</Callout>

### 通配符支持 [#通配符支持]

可在可信来源中使用通配符模式：

```ts
export const auth = betterAuth({
	trustedOrigins: [
		"https://*.example.com", // 信任 example.com 的所有 HTTPS 子域
		"http://*.dev.example.com" // 信任 dev.example.com 的所有 HTTP 子域
	]
})
```

#### 模式语法 [#模式语法]

| 模式   | 描述                 |
| ---- | ------------------ |
| `?`  | 匹配恰好一个字符（不包括 `/`）  |
| `*`  | 匹配零个或多个不跨越 `/` 的字符 |
| `**` | 匹配零个或多个字符（包括 `/`）  |

#### 模式示例 [#模式示例]

| 模式                       | 匹配                                                                                       | 不匹配                                                 |
| ------------------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `http://*.example.com`   | `http://api.example.com`<br />`http://app.example.com`<br />`http://api.app.example.com` | `https://api.example.com`<br />`http://example.com` |
| `https://**.example.com` | `https://api.example.com`<br />`https://api.app.example.com`                             | `http://api.example.com`                            |
| `https://example.com`    | `https://example.com`<br />`https://example.com/path`                                    | `https://api.example.com`<br />`http://example.com` |
| `exp://192.168.*.*:*/**` | `exp://192.168.1.100:8081/path`<br />`exp://192.168.50.200:19000/auth/callback`          | `exp://10.0.0.29:8081/path`                         |
| `myapp://`               | 所有以 `myapp://` 开头的 URL                                                                   | -                                                   |

<Callout type="info">
  **注意**

  * 对于 `http://` 和 `https://` URL，模式会匹配完整来源。路径和查询字符串会被忽略。
  * 对于自定义协议（如 `exp://` 或 `myapp://`），通配符模式会针对包含路径在内的完整 URL 进行匹配。非通配符模式会根据协议和权限进行匹配：不包含主机的条目（如 `myapp://` 或 `exp://`）会信任该协议的所有主机，而包含主机的条目（如 `myapp://callback`）必须精确匹配该主机（因此不会被 `myapp://callback.attacker.tld` 满足）。
  * 分隔符是 `/`（正斜杠）。这意味着 `http://*.example.com` 同时匹配 `http://api.example.com` 和 `http://api.app.example.com`。
</Callout>

## `secret` [#secret]

用于加密、签名和哈希的密钥。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secret: "your-secret-key",
})
```

默认情况下，Better Auth 会查找以下环境变量：

* `process.env.BETTER_AUTH_SECRET`

* `process.env.AUTH_SECRET`

* `process.env.BETTER_AUTH_SECRET`

* `process.env.AUTH_SECRET`

如果两者都未设置，默认为 `"better-auth-secret-12345678901234567890"`。在生产环境中如果未设置将抛出错误。

你可以使用以下命令生成密钥：

```bash
openssl rand -base64 32
```

## `secrets` [#secrets]

版本化密钥用于在相同加密格式和用途内无破坏性地轮换密钥。设置后，加密数据会使用嵌入密钥版本的信封格式；只要相应用途的密钥仍在配置中，就可以轮换密钥而不使已加密数据失效。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secrets: [
		{ version: 2, value: "new-secret-key" },
		{ version: 1, value: "old-secret-key" },
	],
})
```

* 第一个条目是所有新加密使用的**当前**密钥。
* 剩余条目是**仅用于解密**（之前的轮换）。
* 版本为整数。允许存在空缺（例如在撤销 version 2 后，可能是 `1, 3`）。

也可通过 `BETTER_AUTH_SECRETS` 环境变量设置：

```txt title=".env"
BETTER_AUTH_SECRETS=2:new-secret-base64,1:old-secret-base64
```

设置 `secrets` 时，单数形式的 `secret` 仅用于解密相同加密用途下、早于信封格式的旧数据。迁移期间两者可以共存。从共享密钥升级到用途专属密钥时，保留旧 `secret` 并不能保留待处理的 OAuth 或 SAML state cookie，也不能保留 OAuth Proxy 载荷。切换要求请参阅[安全参考](/docs/reference/security#secret-rotation)。

## `database` [#database]

Better Auth 的数据库配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	database: {
		dialect: "postgres",
		type: "postgres",
		casing: "camel"
	},
})
```

Better Auth 支持多种数据库配置，包括 [PostgreSQL](/docs/adapters/postgresql)、[MySQL](/docs/adapters/mysql) 和 [SQLite](/docs/adapters/sqlite)。

阅读更多关于 [数据库](/docs/concepts/database)。

## `secondaryStorage` [#secondarystorage]

用于存储会话数据、验证记录和速率限制数据的二级存储配置。

```ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
	// ... 其他选项
    secondaryStorage: {
    	// 你的实现
    },
})
```

阅读更多关于 [二级存储](/docs/concepts/database#二级存储)。

## `emailVerification` [#emailverification]

邮箱验证配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	emailVerification: {
		sendVerificationEmail: async ({ user, url, token }) => {
			// 向用户发送验证邮件
		},
		sendOnSignUp: true,
		autoSignInAfterVerification: true,
		expiresIn: 3600 // 1 小时
	},
})
```

* `sendVerificationEmail`: 发送验证邮件的函数
* `sendOnSignUp`: 注册成功后自动发送验证邮件。`true` 总会发送，`false` 从不发送，`undefined` 将遵循 `requireEmailVerification` 的行为（默认：`undefined`）
* `sendOnSignIn`: 当用户登录且其邮箱尚未验证时，自动发送验证邮件（默认：`false`）
* `autoSignInAfterVerification`: 用户在验证邮箱后自动登录
* `expiresIn`: 验证令牌的有效期（秒）（默认：`3600` 秒）

## `emailAndPassword` [#emailandpassword]

邮箱密码认证配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	emailAndPassword: {
		enabled: true,
		disableSignUp: false,
		requireEmailVerification: true,
		minPasswordLength: 8,
		maxPasswordLength: 128,
		autoSignIn: true,
		sendResetPassword: async ({ user, url, token }) => {
			// 发送重置密码邮件
		},
		resetPasswordTokenExpiresIn: 3600, // 1 小时
		password: {
			hash: async (password) => {
				// 自定义密码哈希
				return hashedPassword;
			},
			verify: async ({ hash, password }) => {
				// 自定义密码验证
				return isValid;
			}
		},
	},
})
```

* `enabled`：启用邮箱与密码认证（默认：`false`）
* `disableSignUp`：禁用邮箱与密码注册（默认：`false`）
* `requireEmailVerification`：在创建会话前要求进行邮箱验证
* `minPasswordLength`：最小密码长度（默认：`8`）
* `maxPasswordLength`：最大密码长度（默认：`128`）
* `autoSignIn`：用户注册后自动登录
* `sendResetPassword`：发送重置密码邮件的函数
* `onPasswordReset`：用户密码重置后触发的回调。新密码保存后调用；启用 `revokeSessionsOnPasswordReset` 时，会在会话撤销后调用
* `revokeSessionsOnPasswordReset`：重置密码时撤销用户的所有会话。对于数据库会话，如果适配器启用了事务，会在同一事务中完成撤销与密码修改。二级存储中的会话会在提交后尽力删除（默认：`false`）
* `resetPasswordTokenExpiresIn`：重置密码令牌的有效期（秒）（默认：`3600` 秒）
* `onExistingUserSignUp`：有人使用已注册的邮箱注册时触发的回调。仅在 `requireEmailVerification` 为 `true` 或 `autoSignIn` 为 `false` 时调用（默认：`undefined`）。
* `customSyntheticUser`：用于构建自定义合成用户的函数，以防止邮箱枚举。插件向用户表添加字段时可使用。参见[邮箱枚举防护](/docs/authentication/email-password#plugins-that-add-user-fields)。
* `password`：自定义密码哈希与验证函数

## `socialProviders` [#socialproviders]

社交登录提供商配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	socialProviders: {
		google: {
			clientId: "your-client-id",
			clientSecret: "your-client-secret",
			redirectURI: "https://example.com/api/auth/callback/google"
		},
		github: {
			clientId: "your-client-id",
			clientSecret: "your-client-secret",
			redirectURI: "https://example.com/api/auth/callback/github"
		}
	},
})
```

* `clientId`：提供商提供的 OAuth 客户端 ID
* `clientSecret`：提供商提供的 OAuth 客户端密钥
* `clientKey`：客户端密钥（某些提供商（如 TikTok）使用它代替 clientId）（可选）
* `redirectURI`：OAuth 回调的自定义重定向 URI（可选）
* `scope`：要请求的其他 OAuth 作用域（可选）
* `mapProfileToUser`：将提供商资料映射到用户的自定义函数（可选）
* `disableSignUp`：禁止新用户注册（可选）
* `disableImplicitSignUp`：禁止新用户隐式注册（可选）
* `overrideUserInfoOnSignIn`：登录时使用提供商用户信息覆盖用户信息（可选）
* `requireEmailVerification`：在创建会话前要求验证此提供商的邮箱。按提供商单独启用，并且独立于 `emailAndPassword.requireEmailVerification`。仅对报告可信 `email_verified` 信号的提供商启用（可选）
* `prompt`：授权码请求使用的提示方式（`"select_account"`、`"consent"`、`"login"`、`"none"`、`"select_account consent"`）（可选）
* `responseMode`：使用的响应模式（`"query"`、`"form_post"`）（可选）
* `getUserInfo`：从提供商获取用户信息的自定义函数（可选）
* `refreshAccessToken`：刷新令牌的自定义函数。接收存储的刷新令牌并返回新的 OAuth 令牌（可选）
* `verifyIdToken`：验证 ID 令牌的自定义函数。接收 `(token, nonce?, ctx?)`，其中 `ctx` 是请求端点上下文（可选）。设置后会替代提供商内置的验证逻辑
* `disableIdTokenSignIn`：禁止使用从客户端发送的 ID 令牌登录（可选）
* `disableDefaultScope`：禁用提供商的默认作用域（可选）
* `authorizationEndpoint`：自定义授权端点 URL（可选）

## `plugins` [#plugins]

Better Auth 插件列表。

```ts
import { betterAuth } from "better-auth";
import { emailOTP } from "better-auth/plugins";

export const auth = betterAuth({
	plugins: [
		emailOTP({
			sendVerificationOTP: async ({ email, otp, type }) => {
				// 向用户邮箱发送 OTP
			}
		})
	],
})
```

## `user` [#user]

用户配置选项。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	user: {
		modelName: "users",
		fields: {
			email: "emailAddress",
			name: "fullName"
		},
		additionalFields: {
			customField: {
				type: "string",
			}
		},
		changeEmail: {
			enabled: true,
			sendChangeEmailConfirmation: async ({ user, newEmail, url, token }) => {
				// 向旧邮箱发送变更确认邮件
			},
			updateEmailWithoutVerification: false // 用户未验证时是否直接更新邮箱
		},
		deleteUser: {
			enabled: true,
			sendDeleteAccountVerification: async ({ user, url, token }) => {
				// 发送删除账号验证邮件
			},
			beforeDelete: async (user) => {
				// 删除用户前执行操作
			},
			afterDelete: async (user) => {
				// 删除用户后清理工作
			}
		}
	},
})
```

* `modelName`：用户的模型名称（默认：`"user"`）
* `fields`：将字段映射到不同的列名
* `additionalFields`：用户表的附加字段
* `changeEmail`：更改邮箱的配置
* `deleteUser`：用户删除的配置。

## `session` [#session]

会话配置选项。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	session: {
		modelName: "sessions",
		fields: {
			userId: "user_id"
		},
		expiresIn: 604800, // 7 天
		updateAge: 86400, // 1 天
		disableSessionRefresh: true, // 禁用会话刷新，不根据 `updateAge` 更新会话（默认：`false`）
		additionalFields: { // 会话表额外字段
			customField: {
				type: "string",
			}
		},
		storeSessionInDatabase: true, // 提供二级存储时存数据库（默认：`false`）
		preserveSessionInDatabase: false, // 在二级存储删除后保留数据库中会话记录（默认：`false`）
		cookieCache: {
			enabled: true, // 在 cookie 中缓存会话（默认：`false`）
			maxAge: 300, // 5 分钟
			strategy: "jwt"
		}
	},
})
```

* `modelName`：会话的模型名称（默认：`"session"`）
* `fields`：将字段映射到不同的列名
* `expiresIn`：会话令牌过期时间（秒）（默认：`604800` - 7 天）
* `updateAge`：会话需要刷新的频率（秒）（默认：`86400` - 1 天）
* `additionalFields`：会话表的附加字段
* `storeSessionInDatabase`：在提供二级存储时，将会话存入数据库（默认：`false`）
* `preserveSessionInDatabase`：当从二级存储删除会话时，在数据库中保留会话记录（默认：`false`）
* `cookieCache`：启用在 cookie 中缓存会话。

## `account` [#account]

账号配置选项。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	account: {
		modelName: "accounts",
		fields: {
			userId: "user_id"
		},
		encryptOAuthTokens: true, // 在存入数据库前加密 OAuth 令牌
		storeStateStrategy: "database", // 在验证存储中存储 OAuth 状态负载
		storeAccountCookie: true, // 在 OAuth 流程后将提供商账号数据存储在加密 cookie 中（对无数据库流程很有用）
		accountLinking: {
			enabled: true,
			trustedProviders: ["google", "github", "email-password"], // 或异步函数 (request) => ["google", "github"]
			allowDifferentEmails: false
		},
	},
})
```

* `modelName`：账号的模型名称
* `fields`：将字段映射到不同的列名

### `encryptOAuthTokens` [#encryptoauthtokens]

在存入数据库前加密 OAuth 令牌。默认为 `false`。

### `updateAccountOnSignIn` [#updateaccountonsignin]

启用后，登录时使用提供商最新数据（accessToken、idToken、refreshToken 等）更新用户账号。

### `storeStateStrategy` [#storestatestrategy]

控制 OAuth 状态数据在认证流程中的存储位置。

* `"cookie"`：将状态负载存储在加密 cookie 中。这样 OAuth 状态保持无状态，并避免在流程开始时写入数据库。
* `"database"`：将状态负载存储在验证存储/表中，在开始流程时设置已签名的 state cookie，并在 OAuth 回调请求中将浏览器发送的已签名 cookie 与存储的状态进行校验。

当配置了数据库或 `secondaryStorage` 时，默认使用 `"database"`；只有在两者都未设置（完全无状态方案）时才使用 `"cookie"`。使用 `secondaryStorage` 时，OAuth 状态会自动存储在那里；你不再需要手动设置。

加密 cookie 是流程中的凭证，不是持久化存储格式。从直接使用 `BETTER_AUTH_SECRET` 加密此 cookie 的版本升级到派生用途专属密钥的版本时，应同时升级所有为同一 auth base 提供服务的节点。切换前开始的 OAuth 登录、账户关联以及使用 cookie 存储 state 的 SAML 登录都必须重新启动。版本混用可能返回 [`state_invalid`](/docs/reference/errors/state_invalid)，Better Auth 不会回退到之前的共享密钥。

### `storeAccountCookie` [#storeaccountcookie]

在 OAuth 流程后将提供商账号数据存储在加密 cookie 中。这对无数据库流程很有用，因为此时必须在没有账号表的情况下获取 OAuth 令牌材料，例如 access token、refresh token、ID token、作用域和令牌过期信息。

* 默认值：`false`
* 如果未提供数据库，会自动设置为 `true`

账号 cookie 的最大有效期为五分钟，并会在 Better Auth 写入更新后的提供商账号数据时刷新，例如在 `getAccessToken` 或 `/refresh-token` 刷新提供商令牌后。发生这种情况时，如果是在服务端代码中，请将返回的 `Set-Cookie` 头转发给浏览器，以保留刷新的账号 cookie。

在 `getAccessToken`、`refreshToken` 或 `accountInfo` 中传入 `useAccountCookie: true`，即可让已签名 cookie 选择账号。这些 API 要求显式提供 `accountId` 或 `useAccountCookie: true`；两者都省略则无效。

Better Auth 会将过大的账号 cookie 分块，但浏览器和代理仍可能限制 cookie 或请求头的总大小。对于会签发大型 JWT 的提供商，或需要持久化令牌存储的生产流程，建议使用基于数据库的账号存储。

启用此选项后，你可以在 hooks 或 middleware 中通过 `better-auth/cookies` 的 `getAccountCookie` 读取解密后的账号 cookie：

```ts
import { createAuthMiddleware } from "better-auth/api";
import { getAccountCookie } from "better-auth/cookies";

const hook = createAuthMiddleware(async (ctx) => {
	const account = await getAccountCookie(ctx);
});
```

### `accountLinking` [#accountlinking]

账号关联配置。

* `enabled`: 启用账号关联（默认：`true`）
* `disableImplicitLinking`: 禁用 OAuth 登录时的自动账号关联。当为 `true` 时，具有相同邮箱的现有用户在 OAuth 登录时会返回 `account_not_linked`，而不会被隐式关联（即使邮箱已验证或属于 `trustedProviders`）。新用户仍然可以通过 OAuth 注册，已认证用户也仍然可以通过 `linkSocial()` 显式关联提供商。（默认：`false`）
* `trustedProviders`: 受信任提供商列表。可以是静态数组，也可以是根据请求动态返回提供商的异步函数（类似 `trustedOrigins`）
* `allowDifferentEmails`: 允许用户使用不同的电子邮件地址关联账号
* `allowUnlinkingAll`: 允许用户解除所有账号关联
* `updateUserInfoOnLink`: 关联时，将提供商资料（`name`、`image` 以及任何 `mapProfileToUser` 字段）复制到本地用户。不会更改本地 `email` 和 `emailVerified`。（默认：`false`）

## `verification` [#verification]

验证相关配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secondaryStorage: {
		// 你的 Redis 或 KV 实现
	},
	verification: {
		disableCleanup: false,
		storeIdentifier: "hashed",
		storeInDatabase: false
	},
})
```

* `modelName`: 验证表的模型名称
* `fields`: 将字段映射到不同的列名
* `disableCleanup`: 当获取某个验证值时，禁用清理过期值
* `storeIdentifier`: 如何存储诸如 token 和 OTP key 之类的验证标识符。支持 `"plain"`、`"hashed"` 或自定义哈希器。你也可以使用 `{ default, overrides }` 来对每个标识符前缀应用不同策略。
* `storeInDatabase`: 即使配置了 `secondaryStorage`，也将验证记录存入数据库。默认值：`false`。

使用 `storeIdentifier.overrides` 时，Magic Link 标识符以 `magic-link:` 开头，数据库存储的 OAuth 和 SAML relay state 标识符以 `auth-state:` 开头。覆盖规则会在标识符存储或哈希前匹配这些前缀。此前缀仅用于验证存储；Magic Link 中发送的令牌，以及发送给 OAuth 提供商或 SAML 身份提供商的 state 均保持不变。

自定义 `storeIdentifier` 哈希器应对完整标识符（包括用途前缀）进行哈希。移除前缀可能导致无关的验证值共用同一存储键，并中断待处理的登录流程。

升级前，请更新针对这些流程的覆盖规则，使其匹配新的前缀。如果存储集成会直接检查验证标识符，也应适配此项变化。共享验证存储的服务器应一起升级。之前签发的 Magic Link 将无法兑换；如果使用 Better Auth 生成的 state 发起的 OAuth 或 SAML 登录在升级前开始，则必须重新启动，无论 state 存储在数据库还是 cookie 中。无需更改验证表 schema，也无需迁移现有用户或账户数据。

如果配置了 `secondaryStorage`，验证记录默认存储在二级存储中。此行为适用于使用 Better Auth 共享验证层的流程，包括 OTP 和魔法链接风格的流程。

## `rateLimit` [#ratelimit]

速率限制配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	rateLimit: {
		enabled: true,
		window: 10,
		max: 100,
		customRules: {
			"/example/path": {
				window: 10,
				max: 100
			}
		},
		storage: "memory",
		modelName: "rateLimit"
	}
})
```

* `enabled`: 启用速率限制（生产环境默认：`true`，开发环境默认：`false`）
* `window`: 用于速率限制的时间窗口。该值应以秒为单位。（默认：`10`）
* `max`: 在时间窗口内允许的默认最大请求数。（默认：`100`）
* `customRules`: 为特定路径应用的自定义速率限制规则。
* `storage`: 存储配置。如果你提供了二级存储，速率限制将存储在二级存储中。（选项：`"memory", "database", "secondary-storage"`，默认：`"memory"`）
* `modelName`: 当数据库用作存储时，速率限制所使用的表名。（默认：`"rateLimit"`）

## `advanced` [#advanced]

高级配置选项。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	advanced: {
		ipAddress: {
			ipAddressHeaders: ["x-client-ip", "x-real-ip"],
			disableIpTracking: false
		},
		useSecureCookies: true,
		disableCSRFCheck: false,
		disableOriginCheck: false,
		crossSubDomainCookies: {
			enabled: true,
			additionalCookies: ["custom_cookie"],
			domain: "example.com"
		},
		cookies: {
			session_token: {
				name: "custom_session_token",
				attributes: {
					httpOnly: true,
					secure: true
				}
			}
		},
		defaultCookieAttributes: {
			httpOnly: true,
			secure: true
		},
		// OAuth 状态配置已移至 account 选项
		// 使用 account.storeStateStrategy 和 account.skipStateCookieCheck
		cookiePrefix: "myapp",
		database: {
			// 自定义 ID 生成器，
			// 禁用生成 ID，让数据库自动生成，
			// 或使用 "serial" 使用数据库自增 ID，或 "uuid" 使用随机 UUID。
			generateId: (((options: {
				model: LiteralUnion<Models, string>;
				size?: number;
			}) => {
				return "my-super-unique-id";
			})) | false | "serial" | "uuid",
			defaultFindManyLimit: 100,
			joins: false,
			validateSchema: true,
		},
		backgroundTasks: {
			handler: (promise) => { /* 如 waitUntil(promise) */ }
		},
		skipTrailingSlashes: true
	},
})
```

* `ipAddress`: 用于速率限制和会话跟踪的 IP 地址配置
  * `disableIpTracking`: 禁用 IP 地址跟踪。
  * `ipAddressHeaders`: 用于读取客户端 IP 地址的受信任请求头名称。
  * `trustedProxies`: 反向代理 IP 或 CIDR 范围。转发链会从右向左遍历，跳过受信任的跳点，首个不受信任的地址会被用作客户端 IP。
* `useSecureCookies`: 默认情况下，生产环境中的 cookie 是安全的。将其设为 `true` 可在所有环境中强制使用 `Secure` cookie 属性。
* `disableCSRFCheck`: 禁用所有 CSRF 防护，包括来源头验证和 Fetch Metadata 检查（⚠️ 安全风险）
* `disableOriginCheck`: 禁用 `callbackURL`、`redirectTo` 以及其他重定向 URL 的 URL 验证（⚠️ 安全风险）
* `crossSubDomainCookies`: 配置可跨子域共享的 cookie
* `cookies`: 自定义 cookie 名称和属性
* `defaultCookieAttributes`: 所有 cookie 的默认属性
* `cookiePrefix`: cookie 前缀
* `database`: 数据库配置选项
* `backgroundTasks`: 配置延迟操作的后台任务处理
* `skipTrailingSlashes`: 在路由匹配中跳过尾随斜杠验证。（默认：`false`）
* OAuth 状态配置选项（`storeStateStrategy`、`skipStateCookieCheck`）现在属于 `account` 选项

<h3 id="advanced-database">
  <code>database</code>
</h3>

为 ID 生成、findMany 查询和数据库连接设置自定义策略。

* `generateId`: 控制记录 ID 的生成方式。接受自定义函数、`false`、`"serial"` 或 `"uuid"`（默认：[随机 base62 字符串](https://github.com/better-auth/better-auth/blob/main/packages/core/src/utils/id.ts)）。更多信息请参阅[数据库文档](/docs/concepts/database#id-生成)。
* `defaultFindManyLimit`: `findMany` 适配器方法返回记录数的默认上限。（默认：`100`）
* `joins`: 为支持联接的适配器启用数据库联接。禁用时（默认），相关数据会通过单独的查询获取。更多信息请参阅[数据库文档](/docs/concepts/database#连接)。（默认：`false`）
* `validateSchema`: 在首次请求前，将架构与 Better Auth 写入的表进行比较，并报告所有差异及其修复方法。更多信息请参阅[数据库文档](/docs/concepts/database#架构验证)。（生产环境之外默认：`true`）

```ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
	advanced: {
		database: {
			generateId: "uuid",
			defaultFindManyLimit: 50,
			joins: true,
		},
	},
});
```

### `backgroundTasks` [#backgroundtasks]

用于配置延迟操作的后台任务处理。后台任务允许非关键操作（如清理、分析、时序攻击缓解或速率限制计数更新）在响应发送后执行，显著提升无服务器平台的响应速度。

一些示例包括 Vercel 上来自 `@vercel/functions` 的 `waitUntil`，以及 Cloudflare Workers 上来自 `cloudflare:workers` 的 `waitUntil`。更多详情请参阅下面的示例。

<Callout type="warn">
  启用该功能会引入最终一致性，即响应返回的是乐观数据，数据库尚未更新。仅当你的应用能接受这种权衡以换取延迟优化时启用。
</Callout>

<Tabs items="[&#x22;Vercel&#x22;, &#x22;Cloudflare Workers&#x22;]">
  <Tab value="Vercel">
    ```ts
    import { betterAuth } from "better-auth";
    import { waitUntil } from "@vercel/functions";

    export const auth = betterAuth({
      advanced: {
        backgroundTasks: {
          handler: waitUntil,
        },
      },
    });
    ```
  </Tab>

  <Tab value="Cloudflare Workers">
    ```ts
    import { betterAuth } from "better-auth";
    import { waitUntil } from "cloudflare:workers";

    export const auth = betterAuth({
      advanced: {
        backgroundTasks: {
          handler: waitUntil,
        },
      },
    });
    ```
  </Tab>
</Tabs>

## `logger` [#logger]

Better Auth 的日志配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		disabled: false,
		disableColors: false,
		level: "warn",
		log: (level, message, ...args) => {
			// 自定义日志实现
			console.log(`[${level}] ${message}`, ...args);
		}
	}
})
```

该配置允许定制 Better Auth 的日志行为，支持选项包括：

* `disabled`: 在设置为 `true` 时禁用所有日志输出（默认：`false`）
* `disableColors`: 禁用默认日志实现中的颜色（默认：由终端的颜色支持情况决定）
* `level`: 设置要显示的最低日志级别（默认：`"warn"`）
  * `"debug"`: 显示所有日志，包括调试信息
  * `"info"`: 显示所有日志，但不包含调试信息
  * `"warn"`: 显示警告和错误
  * `"error"`: 仅显示错误
* `log`: 自定义日志函数，接收：
  * `level`: 日志级别
  * `message`: 日志消息
  * `...args`: 传递给日志器的其他参数

自定义日志示例：

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		level: "info",
		log: (level, message, ...args) => {
			// 将日志发送到自定义日志服务
			myLoggingService.log({
				level,
				message,
				metadata: args,
				timestamp: new Date().toISOString()
			});
		}
	}
})
```

## `databaseHooks` [#databasehooks]

核心操作的数据库生命周期钩子。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	databaseHooks: {
		user: {
			create: {
				before: async (user) => {
					// 在创建用户之前修改数据
					return { data: { ...user, customField: "value" } };
				},
				after: async (user) => {
					// 在创建用户之后执行操作
				}
			},
			update: {
				before: async (userData) => {
					// 在更新用户之前修改数据
					return { data: { ...userData, updatedAt: new Date() } };
				},
				after: async (user) => {
					// 在更新用户之后执行操作
				}
			}
		},
		session: {
			// 会话钩子
		},
		account: {
			// 账号钩子
		},
		verification: {
			// 验证钩子
		}
	},
})
```

## `onAPIError` [#onapierror]

API 错误处理配置。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	onAPIError: {
		throw: true,
		onError: (error, ctx) => {
			// 自定义错误处理
			console.error("Auth error:", error);
		},
		errorURL: "/auth/error",
		customizeDefaultErrorPage: {
			colors: {
				background: "#ffffff",
				foreground: "#000000",
				primary: "#0070f3",
				primaryForeground: "#ffffff",
				mutedForeground: "#666666",
				border: "#e0e0e0",
				destructive: "#ef4444",
				titleBorder: "#0070f3",
				titleColor: "#000000",
				gridColor: "#f0f0f0",
				cardBackground: "#ffffff",
				cornerBorder: "#0070f3"
			},
			size: {
				radiusSm: "0.25rem",
				radiusMd: "0.5rem",
				radiusLg: "1rem",
				textSm: "0.875rem",
				text2xl: "1.5rem",
				text4xl: "2.25rem",
				text6xl: "3.75rem"
			},
			font: {
				defaultFamily: "system-ui, sans-serif",
				monoFamily: "monospace"
			},
			disableTitleBorder: false,
			disableCornerDecorations: false,
			disableBackgroundGrid: false
		}
	},
})
```

* `throw`：发生 API 错误时抛出异常（默认：`false`）
* `onError`：自定义错误处理函数
* `errorURL`：发生错误时重定向的 URL（默认：`/api/auth/error`）
* `customizeDefaultErrorPage`：配置 Better Auth 提供的默认错误页面。启动开发服务器并访问 `/api/auth/error` 查看错误页面。
  * `colors`：自定义错误页面的配色方案
    * `background`：背景颜色
    * `foreground`：前景/文本颜色
    * `primary`：主要强调色
    * `primaryForeground`：主要背景上的文本颜色
    * `mutedForeground`：弱化文本颜色
    * `border`：边框颜色
    * `destructive`：错误/破坏性颜色
    * `titleBorder`：标题的边框颜色
    * `titleColor`：标题文本颜色
    * `gridColor`：背景网格颜色
    * `cardBackground`：卡片背景颜色
    * `cornerBorder`：角落装饰的边框颜色
  * `size`：自定义尺寸和间距
    * `radiusSm`：小边框半径
    * `radiusMd`：中等边框半径
    * `radiusLg`：大边框半径
    * `textSm`：小文本大小
    * `text2xl`：2xl 文本大小
    * `text4xl`：4xl 文本大小
    * `text6xl`：6xl 文本大小
  * `font`：自定义字体族
    * `defaultFamily`：默认字体族
    * `monoFamily`：等宽字体族
  * `disableTitleBorder`：禁用标题周围的边框（默认：`false`）
  * `disableCornerDecorations`：禁用角落装饰（默认：`false`）
  * `disableBackgroundGrid`：禁用背景网格图案（默认：`false`）

## `hooks` [#hooks]

请求生命周期钩子。

```ts
import { betterAuth } from "better-auth";
import { createAuthMiddleware } from "better-auth/api";

export const auth = betterAuth({
	hooks: {
		before: createAuthMiddleware(async (ctx) => {
			// 执行于请求处理前
			console.log("请求路径:", ctx.path);
		}),
		after: createAuthMiddleware(async (ctx) => {
			// 执行于请求处理后
			console.log("响应:", ctx.context.returned);
		})
	},
})
```

更多详情和示例见 [钩子文档](/docs/concepts/hooks)。

## `disabledPaths` [#disabledpaths]

禁用特定的 auth 路径。

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
	disabledPaths: ["/sign-up/email", "/sign-in/email"],
})
```

## `telemetry` [#telemetry]

启用或禁用 Better Auth 的遥测收集。（默认：`false`）

```ts
import { betterAuth } from "better-auth";
export const auth = betterAuth({
  telemetry: {
    enabled: false,
  }
})
```