better-auth

Better Auth 技能

Better Auth 是一个全面且与框架无关的 TypeScript 身份验证/授权框架，内置邮箱/密码、社交 OAuth，并拥有强大的插件生态系统，可支持高级功能。

适用场景

• 在 TypeScript/JavaScript 应用中实现身份验证
• 添加邮箱/密码或社交 OAuth 身份验证
• 配置 2FA、通行密钥、魔法链接等高级身份验证功能
• 构建支持组织功能的多租户应用
• 管理会话和用户生命周期
• 使用任何框架（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express 等）

快速开始

安装

npm install better-auth
# or pnpm/yarn/bun add better-auth

环境配置

创建 .env：

BETTER_AUTH_SECRET=<generated-secret-32-chars-min>
BETTER_AUTH_URL=http://localhost:3000

基本服务端配置

创建 auth.ts（位于根目录、lib/、utils/ 或 src/app/server/ 下）：

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: {
    // See references/database-integration.md
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }
  }
});

数据库架构

npx @better-auth/cli generate  # Generate schema/migrations
npx @better-auth/cli migrate   # Apply migrations (Kysely only)

挂载 API 处理程序

Next.js App Router：

// app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);

**其他框架：**请参阅 references/email-password-auth.md#framework-setup

客户端配置

创建 auth-client.ts：

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_BETTER_AUTH_URL || "http://localhost:3000"
});

基本用法

// Sign up
await authClient.signUp.email({
  email: "[email protected]",
  password: "secure123",
  name: "John Doe"
});

// Sign in
await authClient.signIn.email({
  email: "[email protected]",
  password: "secure123"
});

// OAuth
await authClient.signIn.social({ provider: "github" });

// Session
const { data: session } = authClient.useSession(); // React/Vue/Svelte
const { data: session } = await authClient.getSession(); // Vanilla JS

功能选择矩阵

功能	是否需要插件	用例	参考
邮箱/密码	否（内置）	基本身份验证	email-password-auth.md
OAuth（GitHub、Google 等）	否（内置）	社交登录	oauth-providers.md
邮箱验证	否（内置）	验证邮箱地址	email-password-auth.md
密码重置	否（内置）	忘记密码流程	email-password-auth.md
双重身份验证（2FA/TOTP）	是（twoFactor）	增强安全性	advanced-features.md
通行密钥/WebAuthn	是（passkey）	无密码身份验证	advanced-features.md
魔法链接	是（magicLink）	基于邮箱的登录	advanced-features.md
用户名身份验证	是（username）	用户名登录	email-password-auth.md
组织/多租户	是（organization）	团队/组织功能	advanced-features.md
速率限制	否（内置）	防止滥用	advanced-features.md
会话管理	否（内置）	用户会话	advanced-features.md

身份验证方式选择指南

选择邮箱/密码的情况：

• 构建使用传统身份验证的标准 Web 应用
• 需要全面控制用户凭据
• 面向偏好基于邮箱的账户的用户

选择 OAuth 的情况：

• 希望用户快速注册且流程尽可能顺畅
• 用户已有社交账户
• 需要访问社交资料数据

选择通行密钥的情况：

• 希望提供无密码体验
• 面向使用现代浏览器/设备的用户
• 安全性是首要任务

选择魔法链接的情况：

• 希望实现无密码登录，且避免 WebAuthn 的复杂性
• 面向以邮箱为主的用户
• 需要临时访问链接

组合多种方式的情况：

• 希望满足不同用户偏好的灵活性
• 构建具有多种身份验证需求的企业应用
• 需要渐进式增强（从简单方案开始，再添加更多选项）

核心架构

Better Auth 使用客户端-服务端架构：

1. 服务端（better-auth）：处理身份验证逻辑、数据库操作和 API 路由
2. 客户端（better-auth/client）：为前端提供钩子/方法
3. 插件：扩展服务端和客户端的功能

实现检查清单

• 安装 better-auth 软件包
• 设置环境变量（SECRET、URL）
• 使用数据库配置创建认证服务器实例
• 运行架构迁移（npx @better-auth/cli generate）
• 在框架中挂载 API 处理程序
• 创建客户端实例
• 实现注册/登录界面
• 为组件添加会话管理
• 设置受保护的路由/中间件
• 按需添加插件（之后重新生成架构）
• 测试完整的认证流程
• 配置邮件发送（验证/重置）
• 在生产环境中启用速率限制
• 设置错误处理

参考文档

核心认证

• 电子邮件/密码认证 - 电子邮件/密码设置、验证、密码重置、用户名认证
• OAuth 提供商 - 社交登录设置、提供商配置、令牌管理
• 数据库集成 - 数据库适配器、架构设置、迁移

高级功能

• 高级功能 - 双因素认证/多因素认证、通行密钥、魔法链接、组织、速率限制、会话管理

脚本

• scripts/better_auth_init.py - 通过交互式设置初始化 Better Auth 配置

资源

• 文档：https://www.better-auth.com/docs
• GitHub：https://github.com/better-auth/better-auth
• 插件：https://www.better-auth.com/docs/plugins
• 示例：https://www.better-auth.com/docs/examples