配置选项

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

`appName`

应用程序的名称。

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

`baseURL`

Better Auth的基础URL。这通常是托管应用程序服务器的根URL。

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

如果未明确设置，系统将检查环境变量process.env.BETTER_AUTH_URL

`basePath`

Better Auth的基础路径。这通常是挂载Better Auth路由的路径。

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

默认值：/api/auth

`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";
import { redisStorage } from "better-auth/storage";
 
export const auth = betterAuth({
	secondaryStorage: redisStorage({
		url: "redis://localhost:6379"
	}),
})

在此处阅读更多关于辅助存储的信息。

`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）
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",
				nullable: true
			}
		},
		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",
				nullable: true
			}
		},
		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"
		},
		accountLinking: {
			enabled: true,
			trustedProviders: ["google", "github", "email-password"],
			allowDifferentEmails: false
		}
	},
})

modelName：账户的模型名称
fields：将字段映射到不同的列名

`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的函数

`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";
export const auth = betterAuth({
	hooks: {
		before: async (request, ctx) => {
			// 在处理请求前执行
		},
		after: async (request, response, ctx) => {
			// 在处理请求后执行
		}
	},
})

`disabledPaths`

禁用特定的认证路径。

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

性能优化

Better Auth 应用程序性能优化指南。

为BetterAuth做贡献

BetterAuth贡献指南

开始使用

概念

认证

数据库

集成

插件

指南

参考

性能优化

为BetterAuth做贡献

On this page