配置选项

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 支持多种数据库配置,包括 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: 注册后自动发送验证邮件(默认值: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: 配置跨子域共享的 cookie
  • cookies: 自定义 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,
  }
})