选项

Better Auth 配置选项参考。

Better Auth 配置的所有可用选项列表。详见 Better Auth Options

appName

应用程序的名称。

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

baseURL

Better Auth 的基础 URL。通常是你的应用服务器托管的根 URL。注意:如果 baseURL 中包含路径,则会覆盖默认路径。

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

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

不建议依赖请求推断。为了安全性和稳定性,始终在配置中或通过 BETTER_AUTH_URL 环境变量显式设置 baseURL

basePath

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

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

默认值: /api/auth

trustedOrigins

可信任的来源列表。你可以提供静态数组、动态返回来源的函数,或者使用通配符模式匹配多个域。

静态来源

你可以提供静态数组:

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

动态来源

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

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

request 参数在初始化和直接调用 auth.api 时为 undefined。确保处理此情况并返回默认可信来源。

通配符支持

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

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

模式语法

模式说明
?匹配恰好一个字符(不含 /
*匹配零个或多个字符,但不跨越 /
**匹配零个或多个字符,包括 /

模式示例

模式匹配示例不匹配示例
http://*.example.comhttp://api.example.com
http://app.example.com
http://api.app.example.com
https://api.example.com
http://example.com
https://**.example.comhttps://api.example.com
https://api.app.example.com
http://api.example.com
https://example.comhttps://example.com
https://example.com/path
https://api.example.com
http://example.com
exp://192.168.*.*:*/**exp://192.168.1.100:8081/path
exp://192.168.50.200:19000/auth/callback
exp://10.0.0.29:8081/path
myapp://myapp:// 开头的所有 URL-

注意

  • 对于 http://https:// URL,模式匹配完整来源,路径和查询字符串被忽略。
  • 对于自定义协议(如 exp://myapp://),如果有通配符模式,则对完整 URL(包含路径)匹配;若无通配符,则使用前缀匹配。
  • 分隔符为 /(斜杠),例如 http://*.example.com 匹配 http://api.example.comhttp://api.app.example.com

secret

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

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

默认情况下,Better Auth 会查找以下环境变量:

  • process.env.BETTER_AUTH_SECRET
  • process.env.AUTH_SECRET

如果均未设置,默认为 "better-auth-secret-12345678901234567890"。在生产环境中若未设置将抛出错误。

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

openssl rand -base64 32

secrets

版本化密钥支持无破坏性密钥轮换。设置后,加密数据使用带版本信息的信封格式,可无缝轮换密钥且不影响现有数据。

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secrets: [
		{ version: 2, value: "new-secret-key" },
		{ version: 1, value: "old-secret-key" },
	],
})
  • 第一条是当前用于所有新加密的密钥。
  • 剩余是仅用于解密的旧密钥。
  • 版本为整数,允许跳号(如撤销版本2后保留1和3)。

也可通过 BETTER_AUTH_SECRETS 环境变量设置:

.env
BETTER_AUTH_SECRETS=2:new-secret-base64,1:old-secret-base64

设置 secrets 时,单个 secret 仅作为解密使用旧信封格式数据的备用。迁移期间两者可共存。

database

Better Auth 的数据库配置。

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

Better Auth 支持多种数据库配置,包括 PostgreSQLMySQLSQLite

更多数据库信息见 这里

secondaryStorage

用于存储会话和速率限制数据的二级存储配置。

import { betterAuth } from "better-auth";

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

更多关于二级存储见 这里

emailVerification

邮箱验证配置。

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

邮箱密码认证配置。

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:重置密码时注销其它所有会话(默认:false
  • resetPasswordTokenExpiresIn:重置密码令牌有效期秒数(默认:3600 秒)
  • onExistingUserSignUp:当已有邮箱用户注册时触发的回调,仅在 requireEmailVerificationtrueautoSignInfalse 时调用(默认:undefined
  • customSyntheticUser:自定义合成用户构建函数,用于防止邮箱枚举攻击。当插件向用户表添加字段时使用。详见 邮箱枚举防御
  • password:密码哈希与验证的自定义函数

socialProviders

社交登录提供商配置。

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:登录时用提供商用户信息覆盖用户信息(可选)
  • prompt:授权码请求使用的提示参数(如 "select_account", "consent", "login", "none", "select_account consent")(可选)
  • responseMode:响应模式("query""form_post")(可选)
  • getUserInfo:自定义函数获取提供商用户信息(可选)
  • refreshAccessToken:自定义函数刷新访问令牌(可选)
  • verifyIdToken:自定义函数验证 ID 令牌(可选)
  • disableIdTokenSignIn:禁用客户端发送 ID 令牌进行登录(可选)
  • disableDefaultScope:禁用提供商默认权限范围(可选)
  • authorizationEndpoint:自定义授权端点 URL(可选)

plugins

Better Auth 插件列表。

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

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

user

用户配置选项。

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

会话配置选项。

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 分钟
		}
	},
})
  • modelName:会话模型名(默认:"session")
  • fields:字段映射
  • expiresIn:会话令牌过期时间(秒,默认:604800 即 7 天)
  • updateAge:会话刷新频率(秒,默认:86400 即 1 天)
  • additionalFields:会话表额外字段
  • storeSessionInDatabase:提供二级存储时是否存数据库(默认:false
  • preserveSessionInDatabase:二级存储删除时是否保留数据库记录(默认:false
  • cookieCache:启用 cookie 中缓存会话

account

账号配置选项。

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	account: {
		modelName: "accounts",
		fields: {
			userId: "user_id"
		},
		encryptOAuthTokens: true, // 存数据库前加密 OAuth 令牌
		storeAccountCookie: true, // OAuth 流程后将账号数据存入 cookie(无数据库流常用)
		accountLinking: {
			enabled: true,
			trustedProviders: ["google", "github", "email-password"], // 或异步函数 (request) => ["google", "github"]
			allowDifferentEmails: false
		}
	},
})
  • modelName:账号模型名
  • fields:字段映射

encryptOAuthTokens

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

updateAccountOnSignIn

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

storeAccountCookie

OAuth 流程后将账号数据(访问令牌、刷新令牌等)存入 cookie,适用于无数据库模式。

  • 默认:false
  • 未提供数据库时自动设为 true

启用后,可通过 better-auth/cookiesgetAccountCookie 在钩子或中间件读取解密后的账号 cookie:

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

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

accountLinking

账号关联配置。

  • enabled:启用账号关联(默认:true
  • trustedProviders:可信提供商列表,支持静态数组或异步函数(基于请求动态返回)
  • allowDifferentEmails:允许关联电子邮件不同的账号
  • allowUnlinkingAll:允许解绑所有账号

verification

验证相关配置。

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	verification: {
		modelName: "verifications",
		fields: {
			userId: "user_id"
		},
		disableCleanup: false
	},
})
  • modelName:验证表的模型名
  • fields:字段映射
  • disableCleanup:获取验证值时是否禁用过期数据清理

rateLimit

速率限制配置。

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

高级配置选项。

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	advanced: {
		ipAddress: {
			ipAddressHeaders: ["x-client-ip", "x-forwarded-for"],
			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,
			experimentalJoins: false,
		},
		backgroundTasks: {
			handler: (promise) => { /* 如 waitUntil(promise) */ }
		},
		skipTrailingSlashes: true
	},
})
  • ipAddress:IP 地址相关配置,用于速率限制和会话跟踪
  • useSecureCookies:使用安全 cookie(默认:false
  • disableCSRFCheck:禁用所有 CSRF 保护,包括 Origin 头验证和 Fetch Metadata(⚠️ 存在安全风险)
  • disableOriginCheck:禁用 callbackURLredirectTo 等重定向 URL 的验证(⚠️ 存在安全风险)
  • crossSubDomainCookies:配置跨子域共享 cookie
  • cookies:自定义 cookie 名称和属性
  • defaultCookieAttributes:所有 cookie 默认属性
  • cookiePrefix:cookie 前缀
  • database:数据库配置选项
  • backgroundTasks:配置后台任务处理函数
  • skipTrailingSlashes:跳过路由匹配的尾部斜杠校验(默认:false
  • OAuth 状态配置(storeStateStrategyskipStateCookieCheck)已移至 account 选项

backgroundTasks

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

例如:在 Vercel 上使用 @vercel/functionswaitUntil,或 Cloudflare Workers 上的 ctx.waitUntil。详见下面示例。

启用该功能会引入最终一致性,即响应返回的是乐观数据,数据库尚未更新。仅当你的应用能接受此权衡以换取延迟优化时启用。

import { betterAuth } from "better-auth";
import { waitUntil } from "@vercel/functions";

export const auth = betterAuth({
  advanced: {
    backgroundTasks: {
      handler: waitUntil,
    },
  },
});
import { betterAuth } from "better-auth";
import { AsyncLocalStorage } from "node:async_hooks";

const execCtxStorage = new AsyncLocalStorage<ExecutionContext>();

export const auth = betterAuth({
  advanced: {
    backgroundTasks: {
      handler: (p) => execCtxStorage.getStore()?.waitUntil(p),
    },
  },
});

// 在请求处理时用 execCtxStorage.run(ctx, ...) 包裹

logger

Better Auth 的日志配置。

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:传给日志的其他参数

自定义日志示例:

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

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

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

API 错误处理配置。

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

请求生命周期钩子。

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

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

更多详情和示例见 钩子文档

disabledPaths

禁用特定的 auth 路径。

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

telemetry

启用或禁用 Better Auth 的遥测收集。(默认:false

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