better-auth

用途

Better Auth 是一个面向 TypeScript 的综合性、框架无关的身份认证与授权框架。它用于在 TypeScript/JavaScript 应用中实现认证功能，包括邮箱/密码登录、社交 OAuth 登录，以及通过插件扩展的 2FA、Passkeys、魔法链接、组织/多租户等进阶能力。它可与 Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express 等多种框架配合使用。

主要能力

邮箱/密码认证（内置）：基础认证、邮箱验证、密码重置、用户名登录。
OAuth 社交登录（内置）：支持 GitHub、Google、Discord 等提供商，含提供商配置与令牌管理。
进阶功能（需插件）：
- 双因素认证（2FA/TOTP）：需 twoFactor 插件。
- Passkeys/WebAuthn：需 passkey 插件，实现无密码认证。
- 魔法链接（Magic Link）：需 magicLink 插件，基于邮箱登录。
- 用户名认证：需 username 插件。
- 组织/多租户：需 organization 插件，提供团队/组织功能。
内置能力：限流（防止滥用）、会话管理（用户会话）。

使用方式

安装

npm install better-auth
# 或 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: {
    // 参见 references/database-integration.md
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }
  }
});

数据库 Schema

npx @better-auth/cli generate  # 生成 schema/迁移
npx @better-auth/cli migrate   # 应用迁移（仅 Kysely）

挂载 API Handler（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"
});

基本用法

// 注册
await authClient.signUp.email({
  email: "user@example.com",
  password: "secure123",
  name: "John Doe"
});

// 登录
await authClient.signIn.email({
  email: "user@example.com",
  password: "secure123"
});

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

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

认证方式选择指南

选择邮箱/密码：构建使用传统认证的标准 Web 应用；需要完全控制用户凭据；面向偏好邮箱账户的用户。
选择 OAuth：希望以最小摩擦快速注册；用户已有社交账户；需要访问社交资料数据。
选择 Passkeys：希望无密码体验；面向现代浏览器/设备；安全为最高优先级。
选择魔法链接：希望无密码但不想引入 WebAuthn 复杂度；面向邮箱优先的用户；需要临时访问链接。
组合多种方式：希望为不同用户偏好提供灵活性；构建具有多种认证需求的企业应用；需要渐进增强（从简单开始，逐步增加选项）。

核心架构

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

服务端（better-auth）：处理认证逻辑、数据库操作、API 路由。
客户端（better-auth/client）：为前端提供钩子/方法。
插件：同时扩展服务端与客户端功能。

实施清单

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

适用场景

在 TypeScript/JavaScript 应用中实现认证。
添加邮箱/密码或社交 OAuth 认证。
设置 2FA、Passkeys、魔法链接等进阶认证功能。
构建带组织支持的多租户应用。
管理会话与用户生命周期。
与任意框架（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express 等）配合使用。

参考文档与资源

邮箱/密码认证：邮箱/密码设置、验证、密码重置、用户名认证
OAuth 提供商：社交登录设置、提供商配置、令牌管理
数据库集成：数据库适配器、schema 设置、迁移
进阶功能：2FA/MFA、Passkeys、魔法链接、组织、限流、会话管理
脚本：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

限制

资料未提供关于收费、价格、平台支持范围、性能效果等方面的具体说明，暂未提供。