配置选项
Better Auth 所有可用配置选项列表。详见 Better Auth 选项。
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",
})
如果未显式设置,系统将检查环境变量 process.env.BETTER_AUTH_URL
basePath
Better Auth 的基础路径。通常是挂载 Better Auth 路由的路径。如果 baseURL
中包含路径组件,它将被覆盖。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
basePath: "/api/auth",
})
默认值:/api/auth
trustedOrigins
受信任的源(origins)列表。你可以提供一个静态的源数组、一个动态返回源的函数,或使用通配符模式匹配多个域。
静态源
你可以提供一个静态的源数组:
import { betterAuth } from "better-auth";
export const auth = betterAuth({
trustedOrigins: ["http://localhost:3000", "https://example.com"],
})
动态源
你可以提供一个动态返回源的函数:
export const auth = betterAuth({
trustedOrigins: async (request: Request) => {
// 根据请求返回一个受信任的源数组
return ["https://dynamic-origin.com"];
}
})
通配符支持
您可以在可信来源中使用通配符模式:
export const auth = betterAuth({
trustedOrigins: [
"*.example.com", // 信任 example.com 的所有子域名
"https://*.example.com", // 仅信任 HTTPS 子域名
"http://*.dev.example.com" // 信任 dev.example.com 的 HTTP 子域名
]
})
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-123456789"
。在生产环境中,如果未设置该值,则会抛出错误。
您可以使用以下命令生成一个安全的密钥:
openssl rand -base64 32
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
: 注册后自动发送验证邮件(默认值:false
)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
: 发送重置密码邮件的函数resetPasswordTokenExpiresIn
: 重置密码令牌的有效秒数(默认:3600
秒)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"
}
},
})
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,
sendChangeEmailVerification: async ({ user, newEmail, url, token }) => {
// 发送邮箱变更验证
}
},
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 令牌存储到数据库之前进行加密
accountLinking: {
enabled: true,
trustedProviders: ["google", "github", "email-password"],
allowDifferentEmails: false
}
},
})
modelName
: 账户的模型名称fields
: 将字段映射到不同的列名
encryptOAuthTokens
在将 OAuth 令牌存储到数据库之前进行加密。默认值:false
。
updateAccountOnSignIn
如果启用 (true),用户账户数据(accessToken、idToken、refreshToken 等)将在登录时使用来自提供商的最新数据进行更新。
accountLinking
账户关联配置。
enabled
: 启用账户关联(默认:false
)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,
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
},
cookiePrefix: "myapp",
database: {
// 如果您的数据库使用自增 ID,请将此设置为 true。
useNumberId: false,
// 使用您自己的自定义 ID 生成器,或完全禁用 ID 生成。
generateId: (((options: {
model: LiteralUnion<Models, string>;
size?: number;
}) => {
return "my-super-unique-id";
})) | false,
defaultFindManyLimit: 100,
}
},
})
ipAddress
: 用于速率限制和会话跟踪的 IP 地址配置useSecureCookies
: 使用安全 cookie(默认:false
)disableCSRFCheck
: 禁用受信任来源检查(⚠️ 安全风险)crossSubDomainCookies
: 配置跨子域共享的 cookiecookies
: 自定义 cookie 名称和属性defaultCookieAttributes
: 所有 cookie 的默认属性cookiePrefix
: cookie 前缀generateId
: 为模型生成唯一 ID 的函数
logger
Better Auth 的日志记录器配置。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
logger: {
disabled: false,
level: "error",
log: (level, message, ...args) => {
// 自定义日志记录实现
console.log(`[${level}] ${message}`, ...args);
}
}
})
日志记录器配置允许您自定义 Better Auth 处理日志的方式。它支持以下选项:
disabled
:设置为true
时禁用所有日志记录(默认值:false
)level
:设置要显示的最低日志级别。可用级别包括:"info"
:显示所有日志"warn"
:显示警告和错误"error"
:仅显示错误"debug"
:显示所有日志,包括调试信息
log
:自定义日志记录函数,接收以下参数:level
:日志级别("info"
、"warn"
、"error"
或"debug"
)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("认证错误:", error);
},
errorURL: "/auth/error"
},
})
throw
: 在 API 错误时抛出异常(默认:false
)onError
: 自定义错误处理器errorURL
: 发生错误时重定向的 URL(默认:/api/auth/error
)
hooks
请求生命周期钩子。
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);
})
},
})
更多详细信息和示例,请参阅钩子文档。
disabledPaths
禁用特定的认证路径。
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,
}
})