⚡

BetterAuth身份验证技能Skill better-auth

Better Auth 是一个全面的、框架无关的TypeScript身份验证和授权框架，提供内置的电子邮件/密码认证、社交登录和强大的插件生态系统，适用于高级功能如2FA、passkeys等。关键词：身份验证、授权、TypeScript、框架、OAuth、2FA、插件、数据库、会话管理、网络安全。

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

名称: better-auth 描述: Better Auth 的实现指南 - 一个框架无关的TypeScript身份验证和授权框架。当需要为应用程序添加身份验证功能如电子邮件/密码、OAuth、2FA、passkeys或高级身份验证功能时使用。 许可证: MIT 版本: 1.0.0

Better Auth 技能

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

何时使用此技能

使用此技能当：

  • 在TypeScript/JavaScript应用程序中实现身份验证
  • 添加电子邮件/密码或社交OAuth认证
  • 设置2FA、passkeys、魔法链接或其他高级身份验证功能
  • 构建支持组织的多租户应用程序
  • 实现会话管理和用户管理
  • 与任何框架一起工作（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express等）

核心概念

关键特性

  • 框架无关：与任何框架一起工作（Next.js、Nuxt、Svelte、Remix、Hono、Express等）
  • 内置身份验证方法：电子邮件/密码和OAuth 2.0社交提供商
  • 插件生态系统：易于添加高级功能（2FA、passkeys、魔法链接、用户名、电子邮件OTP、组织等）
  • 数据库灵活性：支持SQLite、PostgreSQL、MySQL、MongoDB等
  • ORM支持：内置适配器用于Drizzle、Prisma、Kysely和MongoDB
  • 类型安全：完整的TypeScript支持，具有优秀的类型推断
  • 会话管理：内置的客户端和服务器会话处理

架构

Better Auth 遵循客户端-服务器架构：

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

安装与设置

步骤1: 安装包

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

步骤2: 环境变量

创建 .env 文件：

BETTER_AUTH_SECRET=<generated-secret-key>
BETTER_AUTH_URL=http://localhost:3000

生成密钥：使用openssl或随机字符串生成器（最小32个字符）。

步骤3: 创建身份验证服务器实例

在项目根目录、lib/、utils/ 或嵌套在 src/、app/、server/ 下创建 auth.ts：

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: {
    // 数据库配置
  },
  emailAndPassword: {
    enabled: true,
    autoSignIn: true // 用户注册后自动登录
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }
  }
});

步骤4: 数据库配置

选择您的数据库设置：

直接数据库连接：

import { betterAuth } from "better-auth";
import Database from "better-sqlite3";
// 或 import { Pool } from "pg";
// 或 import { createPool } from "mysql2/promise";

export const auth = betterAuth({
  database: new Database("./sqlite.db"),
  // 或: new Pool({ connectionString: process.env.DATABASE_URL })
  // 或: createPool({ host: "localhost", user: "root", ... })
});

ORM适配器：

// Drizzle
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "@/db";

export const auth = betterAuth({
  database: drizzleAdapter(db, {
    provider: "pg", // 或 "mysql"、"sqlite"
  }),
});

// Prisma
import { prismaAdapter } from "better-auth/adapters/prisma";
import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();
export const auth = betterAuth({
  database: prismaAdapter(prisma, {
    provider: "postgresql",
  }),
});

// MongoDB
import { mongodbAdapter } from "better-auth/adapters/mongodb";
import { client } from "@/db";

export const auth = betterAuth({
  database: mongodbAdapter(client),
});

步骤5: 创建数据库模式

使用 Better Auth CLI：

# 生成模式/迁移文件
npx @better-auth/cli generate

# 或直接迁移（仅Kysely适配器）
npx @better-auth/cli migrate

步骤6: 挂载API处理器

为 /api/auth/* 创建捕获所有路由：

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);

Nuxt:

// server/api/auth/[...all].ts
import { auth } from "~/utils/auth";

export default defineEventHandler((event) => {
  return auth.handler(toWebRequest(event));
});

SvelteKit:

// hooks.server.ts
import { auth } from "$lib/auth";
import { svelteKitHandler } from "better-auth/svelte-kit";

export async function handle({ event, resolve }) {
  return svelteKitHandler({ event, resolve, auth });
}

Hono:

import { Hono } from "hono";
import { auth } from "./auth";

const app = new Hono();
app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw));

Express:

import express from "express";
import { toNodeHandler } from "better-auth/node";
import { auth } from "./auth";

const app = express();
app.all("/api/auth/*", toNodeHandler(auth));

步骤7: 创建客户端实例

创建 auth-client.ts：

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

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

身份验证方法

电子邮件与密码

服务器配置：

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    autoSignIn: true, // 默认: true
  }
});

客户端用法：

// 注册
const { data, error } = await authClient.signUp.email({
  email: "user@example.com",
  password: "securePassword123",
  name: "John Doe",
  image: "https://example.com/avatar.jpg", // 可选
  callbackURL: "/dashboard" // 可选
}, {
  onSuccess: (ctx) => {
    // 重定向或显示成功
  },
  onError: (ctx) => {
    alert(ctx.error.message);
  }
});

// 登录
const { data, error } = await authClient.signIn.email({
  email: "user@example.com",
  password: "securePassword123",
  callbackURL: "/dashboard",
  rememberMe: true // 默认: true
});

社交OAuth

服务器配置：

export const auth = betterAuth({
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
    // 其他提供商: apple, discord, facebook等
  }
});

客户端用法：

await authClient.signIn.social({
  provider: "github",
  callbackURL: "/dashboard",
  errorCallbackURL: "/error",
  newUserCallbackURL: "/welcome",
});

登出

await authClient.signOut({
  fetchOptions: {
    onSuccess: () => {
      router.push("/login");
    }
  }
});

会话管理

客户端会话

使用钩子 (React/Vue/Svelte/Solid):

// React
import { authClient } from "@/lib/auth-client";

export function UserProfile() {
  const { data: session, isPending, error } = authClient.useSession();

  if (isPending) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;

  return <div>欢迎, {session?.user.name}!</div>;
}

// Vue
<script setup>
import { authClient } from "~/lib/auth-client";
const session = authClient.useSession();
</script>

<template>
  <div v-if="session.data">{{ session.data.user.email }}</div>
</template>

// Svelte
<script>
import { authClient } from "$lib/auth-client";
const session = authClient.useSession();
</script>

<p>{$session.data?.user.email}</p>

使用 getSession:

const { data: session, error } = await authClient.getSession();

服务器端会话

// Next.js
import { auth } from "./auth";
import { headers } from "next/headers";

const session = await auth.api.getSession({
  headers: await headers()
});

// Hono
app.get("/protected", async (c) => {
  const session = await auth.api.getSession({
    headers: c.req.raw.headers
  });

  if (!session) {
    return c.json({ error: "未授权" }, 401);
  }

  return c.json({ user: session.user });
});

插件系统

Better Auth的插件系统允许轻松添加高级功能。

使用插件

服务器端：

import { betterAuth } from "better-auth";
import { twoFactor, organization, username } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    twoFactor(),
    organization(),
    username(),
  ]
});

客户端：

import { createAuthClient } from "better-auth/client";
import {
  twoFactorClient,
  organizationClient,
  usernameClient
} from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    twoFactorClient({
      twoFactorPage: "/two-factor"
    }),
    organizationClient(),
    usernameClient()
  ]
});

添加插件后：

# 重新生成模式
npx @better-auth/cli generate

# 应用迁移
npx @better-auth/cli migrate

热门插件

双因素认证 (2FA)

// 服务器
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [twoFactor()]
});

// 客户端
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [
    twoFactorClient({ twoFactorPage: "/two-factor" })
  ]
});

// 用法
await authClient.twoFactor.enable({ password: "用户密码" });
await authClient.twoFactor.verifyTOTP({
  code: "123456",
  trustDevice: true
});

用户名认证

// 服务器
import { username } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [username()]
});

// 客户端
import { usernameClient } from "better-auth/client/plugins";

// 使用用户名注册
await authClient.signUp.username({
  username: "johndoe",
  password: "securePassword123",
  name: "John Doe"
});

魔法链接

import { magicLink } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, url }) => {
        // 发送带有魔法链接的电子邮件
        await sendEmail(email, url);
      }
    })
  ]
});

Passkey (WebAuthn)

import { passkey } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [passkey()]
});

// 客户端
await authClient.passkey.register();
await authClient.passkey.signIn();

组织/多租户

import { organization } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [organization()]
});

// 客户端
await authClient.organization.create({
  name: "Acme Corp",
  slug: "acme"
});

await authClient.organization.inviteMember({
  organizationId: "org-id",
  email: "user@example.com",
  role: "member"
});

高级配置

电子邮件验证

export const auth = betterAuth({
  emailVerification: {
    sendVerificationEmail: async ({ user, url }) => {
      await sendEmail(user.email, url);
    },
    sendOnSignUp: true
  }
});

速率限制

export const auth = betterAuth({
  rateLimit: {
    enabled: true,
    window: 60, // 秒
    max: 10 // 请求数
  }
});

自定义会话过期

export const auth = betterAuth({
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7天，以秒为单位
    updateAge: 60 * 60 * 24 // 每24小时更新
  }
});

CORS配置

export const auth = betterAuth({
  advanced: {
    corsOptions: {
      origin: ["https://example.com"],
      credentials: true
    }
  }
});

数据库模式

核心表

Better Auth需要这些核心表：

  • user: 用户账户
  • session: 活动会话
  • account: OAuth提供商连接
  • verification: 电子邮件验证令牌

使用CLI自动生成：

npx @better-auth/cli generate

手动模式可在文档中找到： 查看 /docs/concepts/database#core-schema

最佳实践

  1. 环境变量：始终使用环境变量处理密钥
  2. 生产环境使用HTTPS：设置 BETTER_AUTH_URL 为HTTPS URL
  3. 会话安全：在生产中使用安全cookie
  4. 错误处理：在客户端和服务器上实现适当的错误处理
  5. 类型安全：利用TypeScript类型以获得更好的开发体验
  6. 插件顺序：一些插件依赖于其他插件，请检查文档
  7. 数据库迁移：添加插件后始终运行迁移
  8. 速率限制：为生产启用速率限制
  9. 电子邮件验证：为安全实现电子邮件验证
  10. 密码要求：根据需要自定义密码验证

常见模式

受保护路由 (服务器端)

// Next.js中间件
import { auth } from "@/lib/auth";
import { NextRequest, NextResponse } from "next/server";

export async function middleware(request: NextRequest) {
  const session = await auth.api.getSession({
    headers: request.headers
  });

  if (!session) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"]
};

用户资料更新

await authClient.updateUser({
  name: "新名称",
  image: "https://example.com/new-avatar.jpg"
});

密码管理

// 更改密码
await authClient.changePassword({
  currentPassword: "旧密码",
  newPassword: "新密码"
});

// 重置密码（忘记密码）
await authClient.forgetPassword({
  email: "user@example.com",
  redirectTo: "/reset-password"
});

await authClient.resetPassword({
  token: "重置令牌",
  password: "新密码"
});

故障排除

常见问题

  1. “无法找到身份验证实例”

    • 确保 auth.ts 在正确位置（根目录、lib/、utils/）
    • 将身份验证实例导出为 auth 或默认导出

  2. 数据库连接错误

    • 验证数据库凭据
    • 检查数据库服务器是否运行
    • 确保为您的数据库使用正确的适配器

  3. CORS错误

    • 在高级设置中配置 corsOptions
    • 确保客户端和服务器URL匹配

  4. 插件不工作

    • 添加插件后运行迁移
    • 检查插件是否已添加到服务器和客户端
    • 验证插件配置

框架特定指南

  • Next.js：使用Next.js插件进行服务器操作
  • Nuxt：配置服务器中间件
  • SvelteKit：使用hooks.server.ts
  • Astro：正确设置API路由
  • Hono/Express：使用适当的节点处理器

资源

实施检查清单

当实施 Better Auth 时：

  • [ ] 安装 better-auth 包
  • [ ] 设置环境变量（SECRET、URL）
  • [ ] 创建身份验证服务器实例
  • [ ] 配置数据库/适配器
  • [ ] 运行模式迁移
  • [ ] 配置身份验证方法
  • [ ] 挂载API处理器
  • [ ] 创建客户端实例
  • [ ] 实现注册/登录UI
  • [ ] 添加会话管理
  • [ ] 设置受保护路由
  • [ ] 根据需要添加插件
  • [ ] 测试身份验证流程
  • [ ] 配置电子邮件发送（如果需要）
  • [ ] 设置错误处理
  • [ ] 为生产启用速率限制