Better Auth 基础使用指南：快速构建现代化认证系统

前言

在现代 Web 应用中，用户认证系统是核心功能之一。Better Auth 作为一个现代化的认证解决方案，提供了开箱即用的认证功能，同时支持灵活的扩展机制。本文将详细介绍 Better Auth 的基础使用方法，帮助开发者快速构建安全可靠的用户认证系统。

核心认证方式

Better Auth 原生支持两种主流认证方式：

1. 邮箱密码认证 - 传统的邮箱+密码登录方式
2. 社交账号登录 - 支持 Google、GitHub、Apple 等主流社交平台

此外，通过插件系统可以轻松扩展更多认证方式，如用户名登录、魔法链接、Passkey 等。

邮箱密码认证配置

基础配置

启用邮箱密码认证只需简单配置：

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    emailAndPassword: {
        enabled: true  // 启用邮箱密码认证
    }
})

用户注册流程

注册新用户时，调用 signUp.email 方法：

const { data, error } = await authClient.signUp.email({
    email: "user@example.com",  // 用户邮箱
    password: "securePassword123",  // 用户密码(默认至少8位)
    name: "John Doe",  // 用户显示名称
    callbackURL: "/dashboard"  // 验证后跳转地址(可选)
}, {
    onSuccess: (ctx) => {
        // 注册成功处理逻辑
    },
    onError: (ctx) => {
        // 错误处理逻辑
    }
});

默认情况下，用户注册成功后会自动登录。如需禁用此行为：

export const auth = betterAuth({
    emailAndPassword: {
        enabled: true,
        autoSignIn: false  // 禁用注册后自动登录
    }
})

用户登录流程

用户登录使用 signIn.email 方法：

const { data, error } = await authClient.signIn.email({
    email: "user@example.com",
    password: "securePassword123",
    callbackURL: "/dashboard",
    rememberMe: false  // 是否保持长期会话
}, {
    // 回调处理
});

重要安全提示：所有客户端方法都应在浏览器端调用，切勿在服务端直接调用。

社交账号登录

Better Auth 支持多种社交平台登录，包括 GitHub、Google、Apple 等。

服务端配置

首先配置所需的社交平台：

export const auth = betterAuth({
    socialProviders: {
        github: {
            clientId: process.env.GITHUB_CLIENT_ID!,
            clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        },
        google: {
            // Google 配置
        }
    }
})

客户端登录实现

使用 signIn.social 方法实现社交登录：

await authClient.signIn.social({
    provider: "github",  // 社交平台标识
    callbackURL: "/dashboard",  // 成功回调地址
    errorCallbackURL: "/error",  // 错误回调地址
    newUserCallbackURL: "/welcome"  // 新用户回调地址
});

会话管理

客户端会话获取

Better Auth 提供 useSession Hook 方便获取会话信息：

// React 示例
const { data: session, isPending, error } = authClient.useSession();

也支持直接获取会话：

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

服务端会话验证

服务端验证会话需要传递请求头：

// Next.js 示例
const session = await auth.api.getSession({
    headers: await headers()
});

插件系统

Better Auth 的插件系统是其强大之处，以下以双因素认证(2FA)插件为例：

1. 服务端配置

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

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

2. 数据库迁移

执行迁移命令创建所需表结构：

npx @better-auth/cli migrate

3. 客户端集成

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

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

4. 使用2FA功能

// 启用2FA
await authClient.twoFactor.enable({ password });

// 验证TOTP
await authClient.twoFactor.verifyTOTP({
    code: "123456",
    trustDevice: true
});

最佳实践建议

1. 安全配置：始终使用环境变量存储敏感信息如客户端密钥
2. 错误处理：完善所有认证流程的错误处理逻辑
3. 会话管理：合理设置会话过期时间，平衡安全性与用户体验
4. 插件选择：根据实际需求选择合适的认证插件，避免功能冗余

通过本文介绍的基础功能，开发者可以快速搭建一个功能完善、安全可靠的用户认证系统。Better Auth 的模块化设计和插件系统使其能够灵活适应各种应用场景，是现代化Web应用认证的理想解决方案。