Better Auth 深度指南框架无关的 TypeScript 认证框架安装、基础使用与插件生态全解析【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-authBetter Auth 是一个框架无关framework-agnostic的 TypeScript 认证与授权框架开箱即用地提供邮箱密码登录、社交登录、多因素认证、多租户、多会话等全面能力并通过插件生态以极少代码扩展高级功能。本文以仓库 README.md 为骨架结合官方文档安装指南、基础使用、会话管理与核心源码完整讲解从零安装、服务端/客户端配置、邮箱与社交登录、会话读取到二步验证2FA插件接入的全过程读完你可以在自己的 Next.js、Nuxt、Hono、Express 等任意栈中落地一套生产可用的认证体系。Better Auth 是什么解决 TypeScript 生态半成品认证问题官方对 Better Auth 的定位是框架无关的、通用的 TypeScript 认证与授权框架见 docs/content/docs/introduction.mdx。它提供了一整套开箱即用的功能并附带一个插件生态让开发者用极少量代码、在很短时间内为应用加上 2FA、多租户、多会话乃至 SSO、自建身份提供商IDP等复杂能力从而把精力放在真正的业务上。仓库 README 中有一段核心论述Why Better AuthTypeScript 生态中的认证是一个半解决的问题。其他开源库在基础认证之外往往需要大量额外代码。与其仅仅把第三方服务当作答案不如由社区做得更好——这就是 Better Auth 的由来。这一理念直接决定了 Better Auth 的架构取向核心保持精简复杂能力交给插件。从仓库源码看betterAuth工厂函数位于 packages/better-auth/src/auth/full.ts它在full模式下内置了 Kysely 查询构建器支持而当你使用 Drizzle、Prisma、MongoDB 等适配器时官方建议从better-auth/minimal导入以减小打包体积——这是核心精简原则在实现层面的体现。快速上手六步完成安装与初始化Better Auth 的安装流程在 安装指南 中被组织为清晰的步骤。下面按序完整展开所有命令与代码均可直接复制使用。1. 安装包在项目中安装better-authnpm install better-auth # 或使用 pnpm / yarn注意如果你采用前后端分离的架构服务端与客户端两部分都需要安装 Better Auth客户端部分由better-auth/client、better-auth/react等子路径提供。2. 配置环境变量在项目根目录创建.env文件配置两个关键变量BETTER_AUTH_SECRET——用于加密与哈希的密钥至少 32 个字符且必须高熵生成可用以下命令生成openssl rand -base64 32BETTER_AUTH_SECRET你的高熵密钥需要轮换密钥时可使用BETTER_AUTH_SECRETS复数形式平滑切换到新密钥而不使既有数据失效对应secrets配置项。BETTER_AUTH_URL——应用的基础 URLBETTER_AUTH_URLhttp://localhost:3000 # Base URL of your app3. 创建 Better Auth 实例在项目根目录、lib/或utils/下创建auth.ts也支持嵌套在src/、app/、server/下如src/lib/auth.ts。实例必须以变量名auth导出或作为default导出import { betterAuth } from better-auth; export const auth betterAuth({ //... });4. 配置数据库Better Auth 需要数据库存储用户数据支持 SQLite、PostgreSQL、MySQL 等。三种直连方式// SQLite import { betterAuth } from better-auth; import Database from better-sqlite3; export const auth betterAuth({ database: new Database(./sqlite.db), })// PostgreSQL import { betterAuth } from better-auth; import { Pool } from pg; export const auth betterAuth({ database: new Pool({ // connection options }), })// MySQL import { betterAuth } from better-auth; import { createPool } from mysql2/promise; export const auth betterAuth({ database: createPool({ // connection options }), })也可以使用内置 ORM 适配器Drizzle / Prisma / MongoDB// Drizzle import { betterAuth } from better-auth; import { drizzleAdapter } from better-auth/adapters/drizzle; import { db } from /db; // your drizzle instance export const auth betterAuth({ database: drizzleAdapter(db, { provider: pg, // or mysql, sqlite }), });// Prisma import { betterAuth } from better-auth; import { prismaAdapter } from better-auth/adapters/prisma; import { prisma } from /lib/prisma; // your prisma client instance export const auth betterAuth({ database: prismaAdapter(prisma, { provider: postgresql, // or mysql, sqlite, ...etc }), });// MongoDB import { betterAuth } from better-auth; import { mongodbAdapter } from better-auth/adapters/mongodb; import { client } from /db; // your mongodb client export const auth betterAuth({ database: mongodbAdapter(client), });两点补充说明无状态模式若完全不配置数据库可启用 Stateless Session Management无状态会话但大多数插件仍然需要数据库见 demo/stateless 目录中的示例实现体积优化如果使用 Drizzle、Prisma、MongoDB 等数据库适配器建议从better-auth/minimal导入betterAuth以减小打包体积——这正是full与minimal两种入口的差异所在。5. 创建数据库表Better Auth 提供 CLI 工具管理库所需的 schemagenerate——生成 ORM schema 或 SQL 迁移文件npx authlatest generatemigrate——直接在数据库中创建所需表仅内置 Kysely 适配器可用Kysely 用户可直接migrate其余场景建议用generate后手动应用迁移npx authlatest migrate6. 配置认证方式并挂载路由配置内置的邮箱密码与社交登录import { betterAuth } from better-auth; export const auth betterAuth({ //...other options emailAndPassword: { enabled: true, }, socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID as string, clientSecret: process.env.GITHUB_CLIENT_SECRET as string, }, }, });随后在框架的 catch-all 路由中挂载 handler处理/api/auth/*路径的请求除非自定义了 base path。以下为几个典型框架的挂载方式import { auth } from /lib/auth; // path to your auth file import { toNextJsHandler } from better-auth/next-js; export const { POST, GET } toNextJsHandler(auth);import { Hono } from hono; import { auth } from ./auth; // path to your auth file import { serve } from hono/node-server; const app new Hono(); app.on([POST, GET], /api/auth/*, (c) auth.handler(c.req.raw)); serve(app);import express from express; import { toNodeHandler } from better-auth/node; import { auth } from ./auth; const app express(); const port 8000; app.all(/api/auth/*, toNodeHandler(auth)); // Mount body-parsing middleware after the Better Auth handler. app.use(express.json()); app.listen(port, () { console.log(Better Auth app listening on port ${port}); });注意 Express v5 因切换到path-to-regexp6通配路由需写成app.all(/api/auth/{*any}, toNodeHandler(auth))。此外Cloudflare Workers 需要添加nodejs_compat兼容标志Better Auth 依赖 Node.js AsyncLocalStorage 做异步上下文追踪。7. 创建客户端实例客户端库负责与服务端通信支持所有主流 Web 框架及原生 JS。以 React 为例import { createAuthClient } from better-auth/react export const authClient createAuthClient({ /** The base URL of the server (optional if youre using the same domain) */ baseURL: http://localhost:3000 })若 auth 服务端与客户端同域可省略baseURL若使用非默认路径/api/auth则需传入包含完整路径的 URL如http://localhost:3000/custom-path/authVue 从better-auth/vue导入、Svelte 从better-auth/svelte、Solid 从better-auth/solid、原生 JS 从better-auth/client导入也可按需解构导出export const { signIn, signUp, useSession } createAuthClient()仓库中的 demo/nextjs/lib/auth-client.ts 展示了真实项目中客户端实例的组合方式——它同时注册了organizationClient、twoFactorClient、passkeyClient、adminClient、multiSessionClient、oneTapClient等十余个客户端插件并统一配置了fetchOptions.onError处理 429 限流提示。基础使用邮箱密码、社交登录与退出邮箱密码认证服务端开启邮箱密码认证import { betterAuth } from better-auth export const auth betterAuth({ emailAndPassword: { enabled: true } })注册——调用客户端方法signUp.emailimport { authClient } from /lib/auth-client; //import the auth client const { data, error } await authClient.signUp.email({ email, // user email address password, // user password - min 8 characters by default name, // user display name image, // User image URL (optional) callbackURL: /dashboard // A URL to redirect to after the user verifies their email (optional) }, { onRequest: (ctx) { //show loading }, onSuccess: (ctx) { //redirect to the dashboard or sign in page }, onError: (ctx) { // display the error message alert(ctx.error.message); }, });默认注册成功后会自动登录若需关闭自动登录设置autoSignIn: falseimport { betterAuth } from better-auth export const auth betterAuth({ emailAndPassword: { enabled: true, autoSignIn: false //defaults to true }, })登录——调用signIn.emailconst { data, error } await authClient.signIn.email({ /** * The user email */ email, /** * The user password */ password, /** * A URL to redirect to after the user verifies their email (optional) */ callbackURL: /dashboard, /** * remember the user session after the browser is closed. * default true */ rememberMe: false }, { //callbacks })服务端登录——使用auth.api方法。若服务端无法返回 response 对象需手动解析并设置 cookieNext.js 等框架可借助 next 集成 中提到的插件自动处理import { auth } from ./auth; // path to your Better Auth server instance const response await auth.api.signInEmail({ body: { email, password }, asResponse: true // returns a response object instead of data });社交登录Better Auth 内置 Google、GitHub、Apple、Discord 等多家社交提供商。在socialProviders中配置所需提供商import { betterAuth } from better-auth; export const auth betterAuth({ socialProviders: { github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, } }, })客户端调用signIn.socialimport { authClient } from /lib/auth-client; await authClient.signIn.social({ /** * The social provider ID * example github, google, apple */ provider: github, /** * A URL to redirect after the user authenticates with the provider * default / */ callbackURL: /dashboard, /** * A URL to redirect if an error occurs during the sign in process */ errorCallbackURL: /error, /** * A URL to redirect if the user is newly registered */ newUserCallbackURL: /welcome, /** * disable the automatic redirect to the provider. * default false */ disableRedirect: true, });除重定向方式外也可直接用社交提供商返回的idToken或accessToken完成认证免去跳转。退出登录客户端调用signOut可通过fetchOptions在成功时跳转await authClient.signOut({ fetchOptions: { onSuccess: () { router.push(/login); // redirect to login page }, }, });会话Session读取与管理Better Auth 采用传统cookie 会话管理会话存储在 cookie 中随每次请求发送服务端验证后返回用户数据。主session_tokencookie 是服务端会话标识若开启session.cookieCache还会写入独立的session_datacookie 存放短期缓存数据该缓存 cookie 与 JWT 插件的/token端点输出相互独立。会话表结构session表字段如下字段说明id会话唯一标识token会话令牌同时用作会话 cookieuserId用户 IDexpiresAt会话过期时间ipAddress用户 IP 地址userAgent请求的 User-Agent 头会话过期与刷新会话默认7 天过期且每当会话被使用且达到updateAge时过期时间会刷新为当前时间 expiresIn。二者均可配置import { betterAuth } from better-auth export const auth betterAuth({ //... other config options session: { expiresIn: 60 * 60 * 24 * 7, // 7 days updateAge: 60 * 60 * 24 // 1 day (every 1 day the session expiration is updated) } })禁用会话刷新disableSessionRefresh: true使会话不再随updateAge更新延迟刷新deferSessionRefresh默认GET /get-session会写库刷新会话这在读请求路由到只读副本的读写分离架构下会出问题。开启deferSessionRefresh: true后GET 变为只读需要刷新时返回needsRefresh: true由客户端自动调用 POST 完成刷新。会话新鲜度Freshness部分端点要求会话是fresh新鲜的——即会话createdAt在freshAge之内。默认freshAge为 1 天60 * 60 * 24export const auth betterAuth({ session: { freshAge: 60 * 5 // 5 minutes (the session is fresh if created within the last 5 minutes) } })设置freshAge: 0可完全关闭新鲜度检查。客户端读取会话响应式 hookuseSession基于 nanostore 实现支持 React、Vue、Svelte、Solid 及原生 JS会话变化如退出登录会立即反映到 UIimport { authClient } from /lib/auth-client export function User(){ const { data: session, isPending, //loading state error, //error object refetch //refetch the session } authClient.useSession() return ( //... ) }authClient.useSession.subscribe((value){ //do something with the session })一次性获取getSession不想用 hook 时可调用authClient.getSession()也可配合 TanStack Query 等客户端数据请求库使用。服务端读取会话服务端通过auth.api.getSession读取会话必须传入请求的 headers 对象import { auth } from ./auth; import { headers } from next/headers; const session await auth.api.getSession({ headers: await headers() // you need to pass the headers object. })import { auth } from ./auth; app.get(/path, async (c) { const session await auth.api.getSession({ headers: c.req.raw.headers }) });import { auth } from ~/utils/auth; export default defineEventHandler((event) { const session await auth.api.getSession({ headers: event.headers, }) });SvelteKit、Astro、React Router、TanStack Start 等框架的写法与此同构均围绕headers参数展开。插件生态以 2FA 为例的端到端接入插件是 Better Auth 最独特的特性用少量代码为认证系统叠加复杂功能。从 packages/better-auth/src/plugins/index.ts 的导出清单可以看出插件家族的完整面貌包括admin管理员、organization多租户组织、two-factor双因素、passkey、magic-link魔法链接、email-otp邮箱验证码、username、phone-number、jwt、bearer、multi-session多会话、anonymous匿名、one-tapGoogle 一键登录、open-api、oauth-proxy、generic-oauth、captcha、haveibeenpwned密码泄露检测、device-authorization、siwe以太坊登录、one-time-token、custom-session、access、last-login-method等 20 余个官方插件。以双因素认证2FA为例完整的接入过程如下。第 1 步服务端配置导入插件并传入plugins选项import { betterAuth } from better-auth import { twoFactor } from better-auth/plugins export const auth betterAuth({ //...rest of the options plugins: [ twoFactor() ] })此后服务端即拥有 2FA 相关的路由与方法。第 2 步迁移数据库插件通常需要新增表运行 CLI 生成或迁移# 生成 schema供手动迁移 npx auth generate # 或直接迁移内置 Kysely 适配器 npx auth migrate从源码结构看2FA 插件由totp/TOTP 验证码、backup-codes/备用码、otp/与schema.ts组成并配有完整的测试套件two-factor.test.ts、two-factor.security.test.ts、two-factor.attempt-cap.test.ts 等覆盖安全与尝试次数限制场景。第 3 步客户端配置在createAuthClient中注册对应客户端插件import { createAuthClient } from better-auth/client; import { twoFactorClient } from better-auth/client/plugins; const authClient createAuthClient({ plugins: [ twoFactorClient({ twoFactorPage: /two-factor // the page to redirect if a user needs to verify 2nd factor }) ] })启用、禁用 2FA 与验证 TOTP 的完整调用import { authClient } from ./auth-client const enableTwoFactor async() { const data await authClient.twoFactor.enable({ password // the user password is required }) // this will enable two factor } const disableTwoFactor async() { const data await authClient.twoFactor.disable({ password // the user password is required }) // this will disable two factor } const signInWith2Factor async() { const data await authClient.signIn.email({ //... }) //if the user has two factor enabled, it will redirect to the two factor page } const verifyTOTP async() { const data await authClient.twoFactor.verifyTOTP({ code: 123456, // the code entered by the user /** * If the device is trusted, the user wont * need to pass 2FA again on the same device */ trustDevice: true }) }从仓库源码看2FA 的完整实现位于 packages/better-auth/src/plugins/two-factor其中index.ts负责服务端逻辑编排verify-two-factor.ts负责二次验证流程schema.ts定义所需数据表客户端插件位于 packages/better-auth/src/client/plugins。仓库结构导读从源码理解框架分层Better Auth 是一个 pnpm Turborepo 管理的 monorepopackage.json核心工程结构如下packages/better-auth —— 主包聚合导出核心能力入口文件 src/index.ts 从better-auth/core重导出类型、错误码、OAuth2 工具等并导出betterAuth工厂src/auth/full.tspackages/core —— 底层核心上下文、数据库、OAuth2、社交提供商、instrumentation 等packages/cli ——npx auth generate / migrate等命令的实现src/commands各类适配器与存储drizzle-adapter、prisma-adapter、kysely-adapter、mongo-adapter、memory-adapter、redis-storage独立功能包passkey、sso、scim、stripe、oauth-provider、api-key、mcp、cimd、i18n、electron、expo等demo —— 官方演示应用覆盖 nextjs、expo、electron、oidc-client、stateless 等场景是学习各框架集成的活教材docs —— 官方文档站源码含全部 .mdx 文档与llms.txt生成逻辑e2e —— 端到端与集成测试playwright、各框架 demo。对于希望深入源码的读者建议阅读顺序是官方文档docs/content/docs→ 主包packages/better-auth/src→ 核心包packages/core/src→ 具体插件目录。贡献与安全Better Auth 是 MIT 许可的开源项目LICENSE.md你可以自由使用。参与方式包括向源码提交贡献见 CONTRIBUTING.md提交新功能建议与问题报告GitHub Issues。安全漏洞上报若发现安全漏洞请通过 GitHub Security Advisories 私密上报所有报告都会被及时处理并给予相应致谢。生产环境请务必遵守前文的密钥强度要求BETTER_AUTH_SECRET至少 32 字符高熵并合理配置会话过期、刷新与新鲜度策略。总结Better Auth 以核心精简 插件扩展的设计把 TypeScript 认证从半成品补全为开箱即用的完整方案六步即可完成安装、数据库配置、路由挂载与客户端初始化邮箱密码、社交登录、会话管理开箱可用2FA、组织多租户、passkey、SSO 等高级能力通过插件数行接入。无论你的技术栈是 Next.js、Nuxt、SvelteKit、Hono、Express 还是 Cloudflare Workers只要基于标准 Request/Response就能统一获得这套认证能力——这也正是 README 所强调的专注构建你的应用而不是重复造轮子。【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考