首页
/ Payload Better Auth 基础使用指南:构建现代化认证系统

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

2025-06-19 19:33:40作者:邵娇湘

项目概述

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: "user@example.com",
    password: "securePassword123",
    name: "John Doe",
    callbackURL: "/dashboard"
}, {
    onSuccess: (ctx) => {
        // 注册成功后的处理逻辑
    }
});

关键特性:

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

用户登录流程

const { data, error } = await authClient.signIn.email({
    email: "user@example.com",
    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 提供了从基础到高级的全套认证解决方案,通过本文介绍的核心功能和插件系统,开发者可以快速构建安全、灵活且用户友好的认证流程。无论是传统的邮箱密码认证,还是现代化的社交登录和无密码认证,都能得到完美支持。

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

登录后查看全文
热门项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
22
6
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
197
2.17 K
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
208
285
pytorchpytorch
Ascend Extension for PyTorch
Python
59
94
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
974
574
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
9
1
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库,实现网络在NPU上加速计算。
C++
549
81
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
1.02 K
399
communitycommunity
本项目是CANN开源社区的核心管理仓库,包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息
393
27
MateChatMateChat
前端智能化场景解决方案UI库,轻松构建你的AI应用,我们将持续完善更新,欢迎你的使用与建议。 官网地址:https://matechat.gitcode.com
1.2 K
133