⚡

BetterAuth认证框架技能Skill better-auth

Better Auth 是一个框架无关的TypeScript认证授权框架，用于实现Web应用程序的认证、授权、会话管理等功能。支持电子邮件/密码、OAuth、2FA、Passkeys等多种认证方式，提供强大的插件生态系统，适用于前端和后端开发，提升应用安全性。关键词：认证、授权、TypeScript、框架、OAuth、2FA、网络安全、身份管理。

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

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

Better Auth 技能

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

何时使用

  • 在TypeScript/JavaScript应用程序中实现认证
  • 添加电子邮件/密码或社交OAuth认证
  • 设置2FA、Passkeys、魔法链接等高级认证功能
  • 构建支持组织的多租户应用
  • 管理会话和用户生命周期
  • 适用于任何框架（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(); // 原生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
Passkeys/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当：

  • 希望快速注册，最小化摩擦
  • 用户已有社交账户
  • 需要访问社交资料数据

选择Passkeys当：

  • 希望无密码体验
  • 针对现代浏览器/设备
  • 安全性是最高优先级

选择魔法链接当：

  • 希望无密码但无需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、Passkeys、魔法链接、组织、速率限制、会话管理

脚本

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

资源