Better Auth项目迁移指南：从NextAuth.js平滑过渡

迁移背景与准备工作

Better Auth作为一个新兴的身份验证解决方案，相比NextAuth.js提供了更灵活的架构和更丰富的功能集。本指南将详细介绍如何将现有项目从NextAuth.js迁移到Better Auth系统。

在开始迁移前，请确保：

1. 已备份当前项目代码和数据库
2. 已安装Better Auth核心依赖
3. 了解项目当前使用的NextAuth.js版本(v3或v4)

数据库字段映射策略

用户模型(User Schema)调整

NextAuth.js与Better Auth在用户模型字段设计上存在差异，但无需修改数据库结构，可通过映射实现兼容：

export const auth = betterAuth({
  user: {
    fields: {
      emailVerified: {
        // 将datetime类型转换为boolean
        transform: (value) => !!value 
      }
    }
  }
})

会话模型(Session Schema)优化

会话模型需要特别注意时间字段的处理：

model Session {
  id        String   @id @default(cuid())
  expiresAt DateTime @map("expires")      // 映射原expires字段
  token     String   @map("sessionToken") // 映射原sessionToken
  userId    String
  user      User     @relation(fields: [userId], references: [id])
  createdAt DateTime // 新增字段
  updatedAt DateTime // 新增字段
}

账户模型(Account Schema)转换

第三方账户关联模型需要处理多种OAuth字段：

account: {
  fields: {
    accountId: "providerAccountId",
    accessTokenExpiresAt: {
      from: "expires_at",  // 兼容v3和v4不同字段名
      transform: (value) => 
        typeof value === 'number' 
          ? new Date(value * 1000) 
          : value
    }
  }
}

路由处理层改造

将NextAuth.js的路由处理器替换为Better Auth实现：

1. 重命名[...nextauth]目录为[...all]
2. 创建新的路由处理器：

// app/api/auth/[...all]/route.ts
import { toNextJsHandler } from "better-auth/next-js";
import { auth } from "~/server/auth";

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

客户端集成方案

创建Auth客户端实例

// lib/auth-client.ts
import { createAuthClient } from "better-auth/react";

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

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

社交登录改造示例

以Discord登录为例展示改造方法：

export const signInDiscord = async () => {
  try {
    const { url } = await signIn.social({
      provider: "discord",
      callbackUrl: "/dashboard"
    });
    window.location.href = url;
  } catch (error) {
    console.error("登录失败:", error);
  }
};

会话状态管理

替换原有的useSession调用：

function UserProfile() {
  const { data: session, status } = useSession();
  
  if (status === "loading") return <Spinner />;
  
  return (
    <div>
      <h2>{session.user.name}</h2>
      <p>{session.user.email}</p>
    </div>
  );
}

服务端会话处理

在Next.js服务端组件或Action中获取会话：

// app/actions.ts
"use server";

export async function getProtectedData() {
  const session = await auth.api.getSession({
    headers: {
      cookie: headers().get("cookie") 
    }
  });
  
  if (!session) throw new Error("未授权");
  
  // 业务逻辑...
}

中间件保护配置

使用Better Auth实现路由保护：

// middleware.ts
import { auth } from "./auth";
import { NextResponse } from "next/server";

export default auth((req) => {
  if (!req.auth) {
    return NextResponse.redirect(
      new URL("/login", req.url)
    );
  }
});

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

迁移后验证清单

完成迁移后，请验证以下功能：

1. 所有用户能否正常登录/登出
2. 第三方登录提供商是否工作正常
3. 受保护路由是否按预期拦截未授权访问
4. 会话过期机制是否生效
5. 数据库中的现有数据是否被正确读取

高级功能探索

迁移完成后，可以考虑实现Better Auth的进阶特性：

• 多因素认证集成
• 细粒度的权限控制系统
• 实时会话管理
• 自定义身份验证策略

通过本指南，您应该已经成功将项目从NextAuth.js迁移到Better Auth。新系统提供了更强大的扩展能力和更清晰的API设计，将为您的应用带来更好的身份验证体验。