⚡

BetterAuth认证框架Skill better-auth

Better Auth是一个全面的、框架无关的TypeScript认证/授权框架，提供内置的电子邮件/密码认证、社交OAuth、双因素认证、会话管理等功能，适用于各种Web应用程序的身份验证系统。关键词：认证框架、TypeScript、OAuth、2FA、会话管理、网络安全。

身份认证 0 次安装 0 次浏览 更新于 3/17/2026

名称: better-auth 描述: 使用Better Auth实现认证和授权 - 一个框架无关的TypeScript认证框架。功能包括电子邮件/密码认证与验证、OAuth提供商（Google、GitHub、Discord等）、双因素认证（TOTP、SMS）、通行密钥/WebAuthn支持、会话管理、基于角色的访问控制（RBAC）、速率限制和数据库适配器。适用于为应用程序添加认证、实现OAuth流程、设置2FA/MFA、管理用户会话、配置授权规则或为Web应用程序构建安全认证系统。 许可证: MIT 版本: 2.0.0

Better Auth 技能

Better Auth 是一个全面的、框架无关的TypeScript认证/授权框架，内置电子邮件/密码、社交OAuth和强大的插件生态系统，用于高级功能。

何时使用

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

快速入门

安装

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

环境设置

创建 .env:

BETTER_AUTH_SECRET=<生成密钥-最小32字符>
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!,
    }
  }
});

数据库模式

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

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

基本用法

// 注册
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(); // 原生JavaScript

功能选择矩阵

功能 需要插件 使用案例 参考
电子邮件/密码 否（内置） 基本认证 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处理器
  • [ ] 创建客户端实例
  • [ ] 实现注册/登录UI
  • [ ] 向组件添加会话管理
  • [ ] 设置受保护路由/中间件
  • [ ] 根据需要添加插件（之后重新生成模式）
  • [ ] 测试完整的认证流程
  • [ ] 配置电子邮件发送（验证/重置）
  • [ ] 为生产环境启用速率限制
  • [ ] 设置错误处理

参考文档

核心认证

高级功能

  • 高级功能 - 2FA/MFA、通行密钥、魔法链接、组织、速率限制、会话管理

脚本

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

资源