选项

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

【List of all the available options for configuring Better Auth. See Better Auth Options.】

appName

应用的名称。

【The name of the application.】

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

baseURL

Better Auth 的基础 URL。通常这是托管你的应用服务器的根 URL。注意:如果你在 baseURL 中包含路径,它将优先于默认路径。

【Base URL for Better Auth. This is typically the root URL where your application server is hosted. Note: If you include a path in the baseURL, it will take precedence over the default path.】

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

如果没有明确设置,系统将检查环境变量 BETTER_AUTH_URL。如果该变量也未设置,则将从传入请求中推断。

【If not explicitly set, the system will check for the environment variable BETTER_AUTH_URL. If that's also not set, it will be inferred from the incoming request.】

不建议依赖请求推断。为确保安全性和稳定性,请始终在配置中或通过 BETTER_AUTH_URL 环境变量显式设置 baseURL

basePath

Better Auth 的基础路径。通常这是挂载 Better Auth 路由的路径。如果 baseURL 中包含路径组件,则此路径将被覆盖。

【Base path for Better Auth. This is typically the path where the Better Auth routes are mounted. It will be overridden if there is a path component within baseURL.】

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

默认:/api/auth

【Default: /api/auth

trustedOrigins

受信任来源列表。你可以提供一个静态的来源数组,一个动态返回来源的函数,或者使用通配符模式来匹配多个域名。

【List of trusted origins. You can provide a static array of origins, a function that returns origins dynamically, or use wildcard patterns to match multiple domains.】

静态起源

【Static Origins】

你可以提供一个静态的来源数组:

【You can provide a static array of origins:】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	trustedOrigins: ["http://localhost:3000", "https://example.com"],
})

动态起源

【Dynamic Origins】

你可以提供一个动态返回来源的函数:

【You can provide a function that returns origins dynamically:】

export const auth = betterAuth({
	trustedOrigins: async (request) => {
		// request is undefined during initialization and auth.api calls
		if (!request) {
			return ["https://my-frontend.com"];
		}
		// Dynamic logic based on the request
		return ["https://dynamic-origin.com"];
	}
})

在初始化时以及直接调用 auth.api 时,request 参数为 undefined。请确保通过返回默认可信来源来处理这种情况。

通配符支持

【Wildcard Support】

你可以在受信任的来源中使用通配符模式:

【You can use wildcard patterns in trusted origins:】

export const auth = betterAuth({
	trustedOrigins: [
		"https://*.example.com", // trust all HTTPS subdomains of example.com
		"http://*.dev.example.com" // trust all HTTP subdomains of dev.example.com
	]
})

模式语法

【Pattern Syntax】

模式描述
?匹配恰好一个字符(不包括 /
*匹配零个或多个不跨越 / 的字符
**匹配零个或多个包括 / 在内的字符

模式示例

【Pattern Examples】

模式匹配不匹配
http://*.example.comhttp://api.example.com
http://app.example.com
http://api.app.example.com
https://api.example.com
http://example.com
https://**.example.comhttps://api.example.com
https://api.app.example.com
http://api.example.com
https://example.comhttps://example.com
https://example.com/path
https://api.example.com
http://example.com
exp://192.168.*.*:*/**exp://192.168.1.100:8081/path
exp://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.comhttp://api.app.example.com

secret

用于加密、签名和哈希的密钥。

【The secret used for encryption, signing, and hashing.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	secret: "your-secret-key",
})

默认情况下,Better Auth 会查找以下环境变量:

  • process.env.BETTER_AUTH_SECRET
  • process.env.AUTH_SECRET

【By default, Better Auth will look for the following environment variables:

  • process.env.BETTER_AUTH_SECRET
  • process.env.AUTH_SECRET

如果这些环境变量都未设置,它将默认为 "better-auth-secret-123456789"。在生产环境中,如果没有设置,它将抛出错误。

【If none of these environment variables are set, it will default to "better-auth-secret-123456789". In production, if it's not set, it will throw an error.】

你可以使用以下命令生成一个好的密码:

【You can generate a good secret using the following command:】

openssl rand -base64 32

database

Better Auth 的数据库配置。

【Database configuration for Better Auth.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	database: {
		dialect: "postgres",
		type: "postgres",
		casing: "camel"
	},
})

Better Auth 支持多种数据库配置,包括 PostgreSQLMySQLSQLite

【Better Auth supports various database configurations including PostgreSQL, MySQL, and SQLite.】

在此处阅读有关数据库的更多信息 here

【Read more about databases here.】

secondaryStorage

用于存储会话和速率限制数据的二级存储配置。

【Secondary storage configuration used to store session and rate limit data.】

import { betterAuth } from "better-auth";

export const auth = betterAuth({
	// ... other options
    secondaryStorage: {
    	// Your implementation here
    },
})

在此了解有关二级存储的更多信息 here

【Read more about secondary storage here.】

emailVerification

电子邮件验证配置。

【Email verification configuration.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	emailVerification: {
		sendVerificationEmail: async ({ user, url, token }) => {
			// Send verification email to user
		},
		sendOnSignUp: true,
		autoSignInAfterVerification: true,
		expiresIn: 3600 // 1 hour
	},
})
  • sendVerificationEmail:发送验证邮件的函数
  • sendOnSignUp:注册后自动发送验证邮件(默认:false
  • sendOnSignIn:当用户的邮箱未验证时,在登录时自动发送验证邮件(默认值:false
  • autoSignInAfterVerification:在用户验证其电子邮件后自动登录
  • expiresIn:验证令牌有效的秒数(默认值:3600 秒)

emailAndPassword

电子邮件和密码认证配置。

【Email and password authentication configuration.】

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 }) => {
			// Send reset password email
		},
		resetPasswordTokenExpiresIn: 3600, // 1 hour
		password: {
			hash: async (password) => {
				// Custom password hashing
				return hashedPassword;
			},
			verify: async ({ hash, password }) => {
				// Custom password verification
				return isValid;
			}
		}
	},
})
  • enabled:启用电子邮件和密码认证(默认值:false
  • disableSignUp:禁用邮箱和密码注册(默认:false
  • requireEmailVerification:在可以创建会话之前需要进行电子邮件验证
  • minPasswordLength:最小密码长度(默认值:8
  • maxPasswordLength:最大密码长度(默认值:128
  • autoSignIn:注册后自动登录用户
  • sendResetPassword:发送重置密码邮件的函数
  • resetPasswordTokenExpiresIn:重置密码令牌的有效时间,单位为秒(默认:3600 秒)
  • password:自定义密码哈希和验证函数

socialProviders

配置社交登录提供商。

【Configure social login providers.】

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 客户端 ID
  • clientSecret:来自提供商的 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

更好的认证插件列表。

【List of Better Auth plugins.】

import { betterAuth } from "better-auth";
import { emailOTP } from "better-auth/plugins";

export const auth = betterAuth({
	plugins: [
		emailOTP({
			sendVerificationOTP: async ({ email, otp, type }) => {
				// Send OTP to user's email
			}
		})
	],
})

user

用户配置选项。

【User configuration options.】

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 }) => {
				// Send change email confirmation to the old email
			},
			updateEmailWithoutVerification: false // Update email without verification if user is not verified
		},
		deleteUser: {
			enabled: true,
			sendDeleteAccountVerification: async ({ user, url, token }) => {
				// Send delete account verification
			},
			beforeDelete: async (user) => {
				// Perform actions before user deletion
			},
			afterDelete: async (user) => {
				// Perform cleanup after user deletion
			}
		}
	},
})
  • modelName:用户的模型名称(默认值:“user”)
  • fields:将字段映射到不同的列名
  • additionalFields:用户表的附加字段
  • changeEmail:更改电子邮件的配置
  • deleteUser:用户删除的配置

session

会话配置选项。

【Session configuration options.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	session: {
		modelName: "sessions",
		fields: {
			userId: "user_id"
		},
		expiresIn: 604800, // 7 days
		updateAge: 86400, // 1 day
		disableSessionRefresh: true, // Disable session refresh so that the session is not updated regardless of the `updateAge` option. (default: `false`)
		additionalFields: { // Additional fields for the session table
			customField: {
				type: "string",
			}
		},
		storeSessionInDatabase: true, // Store session in database when secondary storage is provided (default: `false`)
		preserveSessionInDatabase: false, // Preserve session records in database when deleted from secondary storage (default: `false`)
		cookieCache: {
			enabled: true, // Enable caching session in cookie (default: `false`)	
			maxAge: 300 // 5 minutes
		}
	},
})
  • modelName:会话使用的模型名称(默认值:"session"
  • fields:将字段映射到不同的列名
  • expiresIn:会话令牌的过期时间,单位为秒(默认:604800 - 7天)
  • updateAge:会话应该以秒为单位刷新的频率(默认值:86400 - 1天)
  • additionalFields:会话表的附加字段
  • storeSessionInDatabase:当提供了辅助存储时,将会话存储在数据库中(默认:false
  • preserveSessionInDatabase:当会话从二级存储中被删除时,保留数据库中的会话记录(默认值:false
  • cookieCache:启用在 cookie 中缓存会话

account

账户配置选项。

【Account configuration options.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	account: {
		modelName: "accounts",
		fields: {
			userId: "user_id"
		},
		encryptOAuthTokens: true, // Encrypt OAuth tokens before storing them in the database
		storeAccountCookie: true, // Store account data after OAuth flow in a cookie (useful for database-less flows)
		accountLinking: {
			enabled: true,
			trustedProviders: ["google", "github", "email-password"],
			allowDifferentEmails: false
		}
	},
})
  • modelName:账户的模型名称
  • fields:将字段映射到不同的列名

encryptOAuthTokens

在将 OAuth 令牌存储到数据库之前进行加密。默认值:false

【Encrypt OAuth tokens before storing them in the database. Default: false.】

updateAccountOnSignIn

如果启用(true),用户账户数据(accessToken、idToken、refreshToken 等)将在登录时使用来自提供者的最新数据进行更新。

【If enabled (true), the user account data (accessToken, idToken, refreshToken, etc.) will be updated on sign in with the latest data from the provider.】

storeAccountCookie

在 OAuth 流程后将账户数据存储在 cookie 中。这对于无需数据库的流程非常有用,在这种情况下,你可以将账户信息(访问令牌、刷新令牌等)存储在 cookie 中,而不是数据库中。

【Store account data after OAuth flow in a cookie. This is useful for database-less flows where you want to store account information (access tokens, refresh tokens, etc.) in a cookie instead of the database.】

  • 默认:false
  • 如果未提供数据库,则自动设置为 true

accountLinking

账户关联配置。

【Configuration for account linking.】

  • enabled:启用账户关联(默认:true
  • trustedProviders:受信任的提供者列表
  • allowDifferentEmails:允许用户关联使用不同电子邮件的账户
  • allowUnlinkingAll:允许用户取消关联所有账户

verification

验证配置选项。

【Verification configuration options.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	verification: {
		modelName: "verifications",
		fields: {
			userId: "user_id"
		},
		disableCleanup: false
	},
})
  • modelName:验证表的模型名称
  • fields:将字段映射到不同的列名
  • disableCleanup:在获取验证值时禁用清理过期值

rateLimit

速率限制配置。

【Rate limiting configuration.】

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

高级配置选项。

【Advanced configuration options.】

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 state configuration has been moved to account option
		// Use account.storeStateStrategy and account.skipStateCookieCheck instead
		cookiePrefix: "myapp",
		database: {
			// Use your own custom ID generator,
			// disable generating IDS so your database will generate them,
			// or use "serial" to use your database's auto-incrementing ID, or "uuid" to use a random UUID.
			generateId: (((options: {
				model: LiteralUnion<Models, string>;
				size?: number;
			}) => {
				return "my-super-unique-id";
			})) | false | "serial" | "uuid",
			defaultFindManyLimit: 100,
			experimentalJoins: false,
		},
		skipTrailingSlashes: true
	},
})
  • ipAddress:用于速率限制和会话跟踪的 IP 地址配置
  • useSecureCookies:使用安全 Cookie(默认值:false
  • disableCSRFCheck:禁用所有 CSRF 保护,包括来源头验证和 Fetch 元数据检查(⚠️ 安全风险)
  • disableOriginCheck:禁用 callbackURLredirectTo 以及其他重定向 URL 的 URL 验证(⚠️ 存在安全风险)
  • crossSubDomainCookies:配置跨子域共享的 Cookie
  • cookies:自定义 cookie 名称和属性
  • defaultCookieAttributes:所有 cookie 的默认属性
  • cookiePrefix:Cookie 的前缀
  • database:数据库配置选项
  • skipTrailingSlashes:在路由匹配时跳过末尾斜杠的验证。(默认值:false
  • OAuth 状态配置选项(storeStateStrategyskipStateCookieCheck)现在是 account 选项的一部分

logger

Better Auth 的日志记录配置。

【Logger configuration for Better Auth.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		disabled: false,
		disableColors: false,
		level: "error",
		log: (level, message, ...args) => {
			// Custom logging implementation
			console.log(`[${level}] ${message}`, ...args);
		}
	}
})

日志记录器配置允许你自定义 Better Auth 处理日志记录的方式。它支持以下选项:

【The logger configuration allows you to customize how Better Auth handles logging. It supports the following options:】

  • disabled:设置为 true 时禁用所有日志(默认值:false
  • disableColors:在默认日志记录器实现中禁用颜色(默认值:由终端的颜色支持情况决定)
  • level:设置要显示的最低日志级别。可用的级别有:
    • "info": 显示所有日志
    • "warn": 显示警告和错误
    • "error":仅显示错误
    • debug:显示所有日志,包括调试信息
  • log:自定义日志函数,接收:
    • level:日志级别("info""warn""error""debug"
    • message: 日志信息
    • ...args:传递给日志记录器的其他参数

自定义日志示例:

【Example with custom logging:】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	logger: {
		level: "info",
		log: (level, message, ...args) => {
			// Send logs to a custom logging service
			myLoggingService.log({
				level,
				message,
				metadata: args,
				timestamp: new Date().toISOString()
			});
		}
	}
})

databaseHooks

核心操作的数据库生命周期钩子。

【Database lifecycle hooks for core operations.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	databaseHooks: {
		user: {
			create: {
				before: async (user) => {
					// Modify user data before creation
					return { data: { ...user, customField: "value" } };
				},
				after: async (user) => {
					// Perform actions after user creation
				}
			},
			update: {
				before: async (userData) => {
					// Modify user data before update
					return { data: { ...userData, updatedAt: new Date() } };
				},
				after: async (user) => {
					// Perform actions after user update
				}
			}
		},
		session: {
			// Session hooks
		},
		account: {
			// Account hooks
		},
		verification: {
			// Verification hooks
		}
	},
})

onAPIError

API 错误处理配置。

【API error handling configuration.】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
	onAPIError: {
		throw: true,
		onError: (error, ctx) => {
			// Custom error handling
			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

请求生命周期钩子。

【Request lifecycle hooks.】

import { betterAuth } from "better-auth";
import { createAuthMiddleware } from "better-auth/api";

export const auth = betterAuth({
	hooks: {
		before: createAuthMiddleware(async (ctx) => {
			// Execute before processing the request
			console.log("Request path:", ctx.path);
		}),
		after: createAuthMiddleware(async (ctx) => {
			// Execute after processing the request
			console.log("Response:", ctx.context.returned);
		})
	},
})

有关更多详情和示例,请参阅 Hooks 文档

【For more details and examples, see the Hooks documentation.】

disabledPaths

禁用特定的认证路径。

【Disable specific auth paths.】

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

telemetry

启用或禁用 Better Auth 的遥测数据收集。(默认值:false

【Enable or disable Better Auth's telemetry collection. (default: false)】

import { betterAuth } from "better-auth";
export const auth = betterAuth({
  telemetry: {
    enabled: false,
  }
})