选项
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
受信任来源列表。您可以提供静态来源数组、动态返回来源的函数,或使用通配符模式匹配多个域。
静态来源
您可以提供静态来源数组:
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_SECRETprocess.env.AUTH_SECRET
如果未设置这些环境变量中的任何一个,它将默认使用 "better-auth-secret-123456789"。在生产环境中,如果未设置,它将抛出错误。
您可以使用以下命令生成一个好的密钥:
openssl rand -base64 32database
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: {
// 如果您的 DB 使用自动递增 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,
disableColors: false,
level: "error",
log: (level, message, ...args) => {
// 自定义日志实现
console.log(`[${level}] ${message}`, ...args);
}
}
})日志记录器配置允许您自定义 Better Auth 处理日志的方式。它支持以下选项:
disabled:设置为true时禁用所有日志记录(默认:false)disableColors:在默认日志记录器实现中禁用颜色(默认:由终端的颜色支持决定)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("Auth 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("Request path:", ctx.path);
}),
after: createAuthMiddleware(async (ctx) => {
// 在处理请求之后执行
console.log("Response:", 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,
}
})