Better Auth 1.4 发布
我们很高兴宣布 Better Auth 1.4 版本发布。本次发布包含多项新功能、性能及安全改进。
升级请运行：
npm install better-auth@1.4🚀 重点功能
无状态认证
现在可以通过在认证配置中省略 database 选项，启用无数据库的无状态会话管理。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
// 无数据库配置
socialProviders: {
google: {
clientId: process.env.GOOGLE_CLIENT_ID,
clientSecret: process.env.GOOGLE_CLIENT_SECRET,
},
},
});此外，还支持无数据库环境下获取 accessToken、accountInfo 和 refreshToken 端点。
import { authClient } from "@/lib/auth-client";
const accessToken = await authClient.getAccessToken();
// 获取账户信息
const accountInfo = await authClient.accountInfo();SCIM 配置管理
SCIM 通过标准协议简化多域场景下身份管理的支持。
import { scim } from "@better-auth/scim";
import { betterAuth } from "better-auth";
export const auth = betterAuth({
plugins: [scim()]
});OAuth 流程中的自定义状态
现在可以在 OAuth 流程中传递任意额外的状态数据。
import { authClient } from "@/lib/auth-client";
await authClient.signIn.social({
provider: "google",
additionalData: {
referralCode: "ABC123",
source: "landing-page",
},
});可在任意钩子、中间件或端点中访问这些额外数据：
import { betterAuth } from "better-auth";
import { getOAuthState, createAuthMiddleware } from "better-auth/api";
const auth = betterAuth({
hooks: {
before: createAuthMiddleware(async (ctx) => {
const additionalData = await getOAuthState<{ referralCode: string, source: string }>();
console.log(additionalData);
})
}
});数据库连接性能改进（实验性）
Better-Auth 现在支持数据库连接，使用数据库连接技术，提升 50 多个端点 2 到 3 倍的响应速度。
启用方法：在认证配置的 experimental 中设置 joins 为 true。
然后重新运行迁移或架构生成以使用支持连接的更新架构。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
experimental: {
joins: true,
},
});虽然数据库连接仍为实验功能，但所有适配器均支持，且将在下一版本中默认启用。
API 密钥支持二级存储
API-Key 插件新增对二级存储的支持，加快密钥查询速度！
import { apiKey } from "@better-auth/api-key";
import { betterAuth } from "better-auth";
export const auth = betterAuth({
secondaryStorage: {
//...
},
plugins: [apiKey({ storage: "secondary-storage" })],
});新默认错误页面
我们重新设计了错误页面，外观更美观且信息更丰富！
你也可以自定义默认错误页面的样式，或替换为自定义路径页面。
SSO 域验证
域验证可让应用自动信任新的 SSO 提供者，通过自动验证关联域的所有权来实现：
👉 详情请阅读域验证
import { sso } from "@better-auth/sso";
import { betterAuth } from "better-auth";
export const auth = betterAuth({
plugins: [sso({ domainVerification: { enabled: true } })],
});CLI 支持数据库索引
Better-Auth CLI 现在内置支持数据库索引，大大提升应用性能。
npx auth generate
npx auth migrateJWT 密钥轮换支持
JWT 插件现支持密钥轮换，允许无停机地替换 JWT 密钥。
import { jwt } from "@better-auth/jwt";
import { betterAuth } from "better-auth";
export const auth = betterAuth({
plugins: [
jwt({
jwks: { rotationInterval: 60 * 60 * 24 * 30, gracePeriod: 60 * 60 * 24 * 30 }
})
],
});改进的通用 OAuth 插件
尚未原生支持的 OAuth 提供者将作为预配置选项加入通用 OAuth 插件，计划最终支持 Auth.js 的所有提供者。
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { keycloak } from "better-auth/plugins/generic-oauth";
export const auth = betterAuth({
plugins: [genericOAuth({
config: [
keycloak({
clientId: process.env.KEYCLOAK_CLIENT_ID,
clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
issuer: process.env.KEYCLOAK_ISSUER,
})
]
})
]
});包体积优化
如果使用自定义适配器（如 Prisma、Drizzle 或 MongoDB），
可通过使用 better-auth/minimal 替代 better-auth 来减小包体积。
该版本不包含 Kysely，仅在直接数据库连接时需要。
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { betterAuth } from "better-auth/minimal";
import { db } from "./database";
export const auth = betterAuth({
database: drizzleAdapter(db, { provider: "pg" }),
});UUID 支持
现在开箱即用支持将 UUID 作为主 ID 字段类型。
import { betterAuth } from "better-auth";
import { db } from "./database";
export const auth = betterAuth({
database: db,
advanced: {
database: { generateId: "uuid" },
},
});改进的邮箱更改流程
为增强安全性，现在可要求用户通过 当前邮箱 确认更改，之后才发送确认邮件到新地址。
import { betterAuth } from "better-auth";
export const auth = betterAuth({
user: {
changeEmail: {
enabled: true,
sendChangeEmailConfirmation: async ({ user, newEmail, url, token }, request) => {
sendEmail({
to: user.email, // 发送到当前邮箱
subject: '批准邮箱更改',
text: `点击链接以批准更改至 ${newEmail}：${url}`
})
}
}
}
});设备授权插件
完整支持 OAuth 2.0 设备授权协议（RFC 8628），允许用户在输入受限设备（智能电视、游戏机等）上登录。
import { betterAuth } from "better-auth";
import { deviceAuthorization } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
deviceAuthorization()
]
});基于 Cookie 的账户存储
现在支持将用户账户数据存储于签名 Cookie 中，非常适合无状态应用或延迟数据库持久化。
export const auth = betterAuth({
account: {
storeAccountCookie: true
}
});⚠️ 破坏性变更
建议逐项检查破坏性变更，确保升级顺利。
现有认证流程
小幅调整以提升流畅度、速度和可靠性。
-
邮箱更改流程：移除
changeEmail流程中的sendChangeEmailVerification，改用emailVerification.sendVerificationEmail。 -
忘记密码流程：将
authClient.forgotPassword改名为authClient.requestPasswordReset。 -
账户信息端点：
accountInfo端点从POST /account-info改为GET /account-info。即所有 auth.api 调用需从：
auth.api.accountInfo({ body: { // ... } });改为：
auth.api.accountInfo({ query: { // ... } });
插件选项变更
多个插件回调中的 request 参数改为 ctx。
Passkey 插件独立成包，API Key 的模拟会话默认关闭。
-
Passkey 插件：已独立为单独包。
立刻安装：
npm install @better-auth/passkey -
Email OTP 插件：
sendVerificationOTP与generateOTP回调现使用ctx替代request，可通过ctx.request访问请求对象。 -
Magic Link 插件：
sendMagicLink回调同样改为ctx，访问请求使用ctx.request。 -
Phone Number 插件：
sendOTP、sendPasswordResetOTP及callbackOnVerification回调参数由request改为ctx，请求对象在ctx.request。 -
Organization 插件：
teams.defaultTeam.customCreateDefaultTeam与teams.maximumTeams回调中的请求参数改用ctx，请求仍可通过ctx.request获取。 -
OIDC 插件：字段
redirectURLs改为redirectUrls，需进行数据库迁移。 -
API Key 插件：API Key 模拟会话默认关闭，需要在认证配置里显式启用。
认证配置变更
数据库配置选项调整。
- 移除
advanced.generateId：已废弃，请使用advanced.database.generateId。 advanced.database.useNumberId迁移：改为advanced.database.generateId: "serial"。
Tanstack Start
Better-Auth 提供的 reactStartCookies 插件迁移为 tanstackStartCookies 插件。
- import { reactStartCookies } from "better-auth/react-start";
+ import { tanstackStartCookies } from "better-auth/tanstack-start";
export const auth = betterAuth({
- plugins: [reactStartCookies()],
+ plugins: [tanstackStartCookies()],
});Expo
Expo 上的 useSession 新增轮询特性，需要安装 expo-network：
npx expo install expo-networkCloudflare 运行时
Better Auth 使用 AsyncLocalStorage 进行异步上下文跟踪。
在 Cloudflare Workers 需于 wrangler.toml 中添加 nodejs_compat 标记以启用：
compatibility_flags = ["nodejs_compat"]
compatibility_date = "2024-09-23"若只需 AsyncLocalStorage 支持：
compatibility_flags = ["nodejs_als"]下一大版本将默认假设支持 AsyncLocalStorage，此配置届时必需。
✨ 更多功能
- Cookie 分块：避免 Cookie 大小超限错误。
- MongoDB 字符串 ID：支持 MongoDB 使用字符串 ID 代替 ObjectID。
- JWE Cookie 缓存：会话存储 Cookie 缓存改为默认使用 JWE，增强安全。
- OIDC RP-发起注销：支持向 OIDC 提供者发起注销。
- 服务器端 IP 识别：自动客户端 IP 检测工具。
- 自定义 OTP 验证：Phone Number 插件现在允许自定义 OTP 验证逻辑。
- 客户端
disableSignal：客户端可关闭默认的 AbortSignal 行为。 AuthClient类型辅助：新增类型辅助，提升客户端类型推导。- 新增提供者：新增 Polar 和 Paybin OAuth 提供者。
- 仅支持 ESM：Better-Auth 完全采用 ESM。
- 会话重新获取：支持轮询及窗口聚焦时刷新会话。
- Cloudflare Workers：CLI 支持虚拟模块导入。
- 错误文档：常见 OAuth 流程错误现已文档化。
- 最后登录方式：支持跟踪 SIWE 与 Passkey 登录方式。
🐛 Bug 修复与改进
本次发布共修复 250+ 个问题，涵盖多个领域：
- 适配器修复：改进查询处理，增强类型转换，支持 UUID 列类型，修复可空外键问题。
- 会话管理：修正会话刷新触发、优化 Cookie 处理和缓存管理。
- OAuth：提升状态管理，改进回调处理，解决跨域问题。
- 组织管理：修复成员删除、团队管理、权限校验和推断相关问题。
- 双因素认证：改进 TOTP 错误消息，修复备用码加密，优化设备信任管理。
- Email OTP：避免重复发送验证邮件，改进会话信号触发。
- SSO：修复 SAML 回调处理，改进 OIDC 范围回退，强化同意机制。
- API-Keys：修复使用统计，改进请求校验。
- Phone Number：阻止未授权手机号更新，优化验证流程。
- 以及更多修复！
大量细节优化让一切更顺畅、更快速、更可靠。
👉 查看完整更新日志
❤️ 贡献者
感谢所有贡献者使本次发布成为可能！