从NextAuth.js迁移到Payload Better Auth的完整指南

前言

在现代Web应用开发中，认证系统是核心功能之一。NextAuth.js曾是Next.js生态中广泛使用的认证解决方案，但随着Payload Better Auth的出现，开发者现在有了更强大、更灵活的选择。本文将详细介绍如何将现有项目从NextAuth.js平滑迁移到Payload Better Auth系统。

迁移前的准备工作

在开始迁移前，需要确保以下几点：

1. 已安装Payload Better Auth并完成基本配置
2. 备份现有数据库，特别是用户认证相关数据
3. 了解现有NextAuth.js实现的所有功能点

数据库字段映射策略

Payload Better Auth采用了与NextAuth.js不同的字段命名约定，但无需修改现有数据库结构，可以通过映射方式实现兼容。

用户模型(User Schema)

Payload Better Auth的用户模型设计非常灵活，通常可以直接兼容现有的用户表结构，无需特殊处理。

会话模型(Session Schema)

会话模型需要进行以下字段映射：

export const auth = betterAuth({
    session: {
        fields: {
            expiresAt: "expires",  // 将expiresAt映射到现有expires字段
            token: "sessionToken"  // 将token映射到现有sessionToken字段
        }
    }
});

账户模型(Accounts Schema)

第三方账户关联模型需要更详细的映射：

export const auth = betterAuth({
    accounts: {
        fields: {
            accountId: "providerAccountId",
            refreshToken: "refresh_token",
            accessToken: "access_token",
            accessTokenExpiresAt: "access_token_expires",
            idToken: "id_token"
        }
    }
});

注意：可以安全移除session_state、type和token_type字段，这些在Payload Better Auth中不再需要。

路由处理器更新

在Next.js项目中，需要更新认证API路由：

1. 将[...nextauth]目录重命名为[...all]
2. 更新路由处理器文件：

import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "~/server/auth";

export const { POST, GET } = toNextJsHandler(auth);

客户端适配层改造

创建认证客户端

在项目lib目录下创建auth-client.ts文件：

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

export const authClient = createAuthClient({
    baseURL: process.env.BASE_URL!
});

export const { signIn, signOut, useSession } = authClient;

社交登录改造

以Discord登录为例：

import { signIn } from "~/lib/auth-client";

export const signInDiscord = async () => {
    return await signIn.social({ provider: "discord" });
};

会话钩子更新

替换所有useSession的使用：

import { useSession } from "~/lib/auth-client";

function Profile() {
    const { data } = useSession();
    // 渲染用户数据...
}

服务端会话处理

在服务端操作中获取会话信息：

"use server";
import { auth } from "~/server/auth";
import { headers } from "next/headers";

export const protectedAction = async () => {
    const session = await auth.api.getSession({
        headers: await headers()
    });
    // 受保护逻辑...
};

中间件保护

Payload Better Auth提供了更灵活的中间件保护方案，可以基于角色、权限等条件进行细粒度的路由保护。

迁移后检查清单

1. 测试所有认证流程：登录、登出、会话续期
2. 验证第三方登录提供商集成
3. 检查受保护路由的访问控制
4. 确认会话数据的一致性

迁移优势总结

完成迁移后，您将获得以下优势：

1. 更简洁的API设计，减少样板代码
2. 更好的类型安全性
3. 更灵活的认证策略配置
4. 更高效的会话管理机制

结语

从NextAuth.js迁移到Payload Better Auth是一个值得投入的过程，它将为您的应用带来更强大、更易维护的认证系统。如果在迁移过程中遇到任何问题，建议查阅Payload Better Auth的详细文档获取更多实现细节和最佳实践。