选项
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.com | http://api.example.comhttp://app.example.comhttp://api.app.example.com | https://api.example.comhttp://example.com |
https://**.example.com | https://api.example.comhttps://api.app.example.com | http://api.example.com |
https://example.com | https://example.comhttps://example.com/path | https://api.example.comhttp://example.com |
exp://192.168.*.*:*/** | exp://192.168.1.100:8081/pathexp://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.com和http://api.app.example.com。
secret
用于加密、签名和哈希的密钥。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
secret: "your-secret-key",
})默认情况下,Better Auth 会查找以下环境变量:
process.env.BETTER_AUTH_SECRETprocess.env.AUTH_SECRET
如果均未设置,默认为 "better-auth-secret-12345678901234567890"。在生产环境中若未设置将抛出错误。
你可以使用以下命令生成密钥:
openssl rand -base64 32secrets
版本化密钥支持无破坏性密钥轮换。设置后,加密数据使用带版本信息的信封格式,可无缝轮换密钥且不影响现有数据。
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 环境变量设置:
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 支持多种数据库配置,包括 PostgreSQL、MySQL 和 SQLite。
更多数据库信息见 这里。
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:当已有邮箱用户注册时触发的回调,仅在requireEmailVerification为true或autoSignIn为false时调用(默认: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 客户端 IDclientSecret:提供商提供的 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/cookies 的 getAccountCookie 在钩子或中间件读取解密后的账号 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:禁用callbackURL、redirectTo等重定向 URL 的验证(⚠️ 存在安全风险)crossSubDomainCookies:配置跨子域共享 cookiecookies:自定义 cookie 名称和属性defaultCookieAttributes:所有 cookie 默认属性cookiePrefix:cookie 前缀database:数据库配置选项backgroundTasks:配置后台任务处理函数skipTrailingSlashes:跳过路由匹配的尾部斜杠校验(默认:false)- OAuth 状态配置(
storeStateStrategy,skipStateCookieCheck)已移至account选项
backgroundTasks
用于配置延迟操作的后台任务处理。后台任务允许非关键操作(如清理、分析、时序攻击缓解或速率限制计数更新)在响应发送后执行,显著提升无服务器平台的响应速度。
例如:在 Vercel 上使用 @vercel/functions 的 waitUntil,或 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,
}
})