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

项目概述

Payload Better Auth 是一个功能强大的认证解决方案，为现代 Web 应用提供了灵活且安全的身份验证机制。本文将详细介绍其核心功能和使用方法，帮助开发者快速构建完善的认证系统。

核心认证方式

1. 邮箱密码认证

基础配置

在项目中启用邮箱密码认证非常简单：

import { betterAuth } from "better-auth"

export const auth = betterAuth({
    emailAndPassword: {
        enabled: true
    }
})

用户注册流程

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

const { data, error } = await authClient.signUp.email({
    email: "[e-mail]",
    password: "securePassword123",
    name: "John Doe",
    callbackURL: "/dashboard"
}, {
    onSuccess: (ctx) => {
        // 注册成功后的处理逻辑
    }
});

关键特性：

• 默认自动登录新注册用户（可通过 autoSignIn: false 禁用）
• 内置密码强度验证（默认最小8个字符）
• 支持注册后回调URL设置

用户登录流程

const { data, error } = await authClient.signIn.email({
    email: "[e-mail]",
    password: "securePassword123",
    rememberMe: false
});

安全提示：

• 永远在客户端调用认证方法，不要在服务端直接调用
• 建议实现失败登录尝试限制

2. 社交账号登录

服务端配置

export const auth = betterAuth({
    socialProviders: {
        google: {
            clientId: process.env.GOOGLE_CLIENT_ID!,
            clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
        },
        github: {
            clientId: process.env.GITHUB_CLIENT_ID!,
            clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        }
    }
})

客户端调用

await authClient.signIn.social({
    provider: "google",
    callbackURL: "/dashboard",
    errorCallbackURL: "/auth-error"
});

支持的主流社交平台：

• Google
• GitHub
• Apple
• Discord
• 等更多平台

会话管理

客户端会话获取

使用 React Hook

function UserProfile() {
    const { data: session, isPending } = authClient.useSession();
    
    if (isPending) return <div>加载中...</div>;
    
    return <div>欢迎, {session?.user.name}</div>;
}

直接获取会话

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

服务端会话验证

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

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

跨框架支持：

• Next.js/Nuxt.js
• SvelteKit
• Astro
• Remix
• Hono
• 等主流框架

插件系统

Payload Better Auth 的强大之处在于其插件系统，可以轻松扩展认证功能。

以双因素认证(2FA)为例

1. 服务端配置

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

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

2. 数据库迁移

npx @better-auth/cli generate
# 或
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. 安全存储密钥：社交登录的 clientSecret 必须妥善保管
2. 错误处理：实现完善的错误处理流程，特别是认证失败场景
3. 会话管理：合理设置会话过期时间，平衡安全性和用户体验
4. 渐进增强：从基础认证开始，逐步添加插件功能
5. 测试策略：确保覆盖各种认证场景的测试用例

总结

Payload Better Auth 提供了从基础到高级的全套认证解决方案，通过本文介绍的核心功能和插件系统，开发者可以快速构建安全、灵活且用户友好的认证流程。无论是传统的邮箱密码认证，还是现代化的社交登录和无密码认证，都能得到完美支持。

对于更高级的使用场景，建议探索插件生态系统，根据项目需求添加如双因素认证、魔法链接等增强功能，打造真正符合业务需求的认证体系。