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 通过标准协议简化多域场景下身份管理的支持。
import { scim } from "@better-auth/scim";
import { betterAuth } from "better-auth";
export const auth = betterAuth({
plugins: [scim()]
});现在可以在 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 提供者，通过自动验证关联域的所有权来实现：
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。
-
邮箱更改流程：已从
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 插件：Passkey 插件现已移至独立包。
立即安装：
npm install @better-auth/passkey -
Email OTP 插件：
sendVerificationOTP和generateOTP的插件选项现在在其回调函数中使用ctx而不是request。你仍然可以通过ctx.request访问请求。 -
Magic Link 插件：
sendMagicLink的插件选项现在在其某个回调选项中使用ctx而不是request。你仍然可以通过ctx.request访问请求。 -
电话号码插件：
sendOTP、sendPasswordResetOTP和callbackOnVerification的插件选项现在在其某个回调选项中用ctx替代了request。你仍然可以通过ctx.request访问请求。 -
组织插件：
teams.defaultTeam.customCreateDefaultTeam和teams.maximumTeams的插件选项现在在其某个回调选项中用ctx替代了request。你仍然可以通过ctx.request访问请求。 -
OIDC 插件：
redirectURLs字段已更新为redirectUrls，这需要进行数据库迁移。 -
API Key 插件：基于 api-key 的模拟会话现在默认禁用，应先通过认证配置显式启用。
认证配置变更
数据库配置选项调整。
- 已移除
advanced.generateId：长期弃用的advanced.generateId已被移除。请改用advanced.database.generateId。 advanced.database.useNumberId已迁移：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"Alternatively, if you only need AsyncLocalStorage support:
compatibility_flags = ["nodejs_als"]下一大版本将默认假设支持 AsyncLocalStorage，此配置届时必需。
✨ 更多功能
- Cookie 分块: 不再出现 Cookie 大小超限错误。
- MongoDB 字符串 ID: 支持在 MongoDB 中使用字符串 ID 而非 ObjectID。
- JWE Cookie 缓存: 会话存储 Cookie 缓存默认使用 JWE 以增强安全性。
- OIDC RP 启动注销: 在 OIDC 提供程序触发注销。
- 服务端 IP 检测: 自动客户端 IP 检测工具。
- 自定义 OTP 验证: 允许在电话号码插件中使用自定义逻辑进行 OTP 验证。
- 客户端
disableSignal: 可选项，用于禁用默认的中止信号行为。 AuthClient类型助手: 新的类型助手，用于更好的客户端类型推断。- 新提供者: 添加了 Polar 和 Paybin OAuth 提供者。
- 仅 ESM: Better-Auth 现在完全支持 ESM。
- 会话重新获取: 支持轮询和窗口聚焦时重新获取。
- Cloudflare Workers: CLI 支持虚拟模块导入。
- 错误文档: 常见的 OAuth 流程错误现已 记录在案。
- 最后登录方式: 支持跟踪 SIWE 和密钥登录。
🐛 错误修复与改进
本次发布共修复 250 多个问题，涵盖多个领域：
- 适配器修复: 改进查询处理、更佳的类型转换 UUID 列类型，并解决了可为空的外键问题。
- 会话管理: 修复会话刷新触发器，改进 Cookie 处理及缓存管理。
- OAuth: 修复状态管理，改进回调处理，并解决跨来源问题。
- 组织: 修复成员删除、团队管理、权限检查和推断问题。
- 双因素认证: 改进 TOTP 错误信息，修复备份代码加密，并增强设备信任处理。
- 电子邮件 OTP: 防止重复发送验证邮件，并改进会话信号触发。
- SSO: 修复 SAML 回调处理，改进 OIDC 作用域回退，并增强同意强制执行。
- API 密钥: 修复使用量跟踪，并改进请求验证。
- 电话号码: 防止未经授权的电话号码更新，并改进验证流程。
- 以及更多！
大量细节优化让一切更顺畅、更快速、更可靠。
👉 查看完整更新日志
❤️ 贡献者
感谢所有贡献者使本次发布成为可能！