从 Clerk 迁移到 Better Auth

在本指南中，我们将逐步介绍如何将项目从 Clerk 迁移到 Better Auth——包括使用正确哈希处理的邮箱/密码、社交/外部账户、手机号、双因素认证数据等。

此迁移将使所有活跃会话失效。本指南目前未涵盖组织（Organization）的迁移，但通过额外步骤和组织插件应该是可以实现的。

开始之前

在开始迁移过程之前，请先在您的项目中设置 Better Auth。请按照安装指南开始操作。并前往

连接到您的数据库

您需要连接到数据库以迁移用户和账户。您可以使用任何您想要的数据库，但在本示例中，我们将使用 PostgreSQL。

npm install pg

然后您可以使用以下代码连接到您的数据库。

auth.ts

import { Pool } from "pg";

export const auth = betterAuth({
    database: new Pool({ 
        connectionString: process.env.DATABASE_URL 
    }),
})

启用邮箱和密码（可选）

在您的认证配置中启用邮箱和密码，并实现您自己的发送验证邮件、重置密码邮件等逻辑。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    database: new Pool({ 
        connectionString: process.env.DATABASE_URL 
    }),
    emailAndPassword: { 
        enabled: true, 
    }, 
    emailVerification: {
      sendVerificationEmail: async({ user, url })=>{
        // 在此处实现发送验证邮件的逻辑
      }
	},
})

更多配置选项请参见邮箱和密码。

配置社交登录提供商（可选）

在您的认证配置中添加已在 Clerk 项目中启用的社交登录提供商。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
    database: new Pool({ 
        connectionString: process.env.DATABASE_URL 
    }),
    emailAndPassword: { 
        enabled: true,
    },
    socialProviders: { 
        github: { 
            clientId: process.env.GITHUB_CLIENT_ID, 
            clientSecret: process.env.GITHUB_CLIENT_SECRET, 
        } 
    } 
})

添加插件（可选）

您可以根据需要向认证配置中添加以下插件。

Admin 插件允许您管理用户、用户模拟以及应用级别的角色和权限。

Two Factor 插件允许您为应用添加双因素认证。

Phone Number 插件允许您为应用添加手机号认证。

Username 插件允许您为应用添加用户名认证。

auth.ts

import { Pool } from "pg";
import { betterAuth } from "better-auth";
import { admin, twoFactor, phoneNumber, username } from "better-auth/plugins";

export const auth = betterAuth({
    database: new Pool({ 
        connectionString: process.env.DATABASE_URL 
    }),
    emailAndPassword: { 
        enabled: true,
    },
    socialProviders: {
        github: {
            clientId: process.env.GITHUB_CLIENT_ID!,
            clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        }
    },
    plugins: [admin(), twoFactor(), phoneNumber(), username()], 
})

生成数据库模式

如果您使用自定义数据库适配器，请生成数据库模式：

npx @better-auth/cli generate

或者如果您使用默认适配器，可以使用以下命令：

npx @better-auth/cli migrate

导出 Clerk 用户

转到 Clerk 仪表板并导出用户。查看如何操作此处。它将下载一个包含用户数据的 CSV 文件。您需要将其保存为 exported_users.csv 并放在项目根目录下。

创建迁移脚本

在 scripts 文件夹中创建一个名为 migrate-clerk.ts 的新文件，并添加以下代码：

scripts/migrate-clerk.ts

import { generateRandomString, symmetricEncrypt } from "better-auth/crypto";

import { auth } from "@/lib/auth"; // 导入您的 auth 实例

function getCSVData(csv: string) {
  const lines = csv.split('\n').filter(line => line.trim());
  const headers = lines[0]?.split(',').map(header => header.trim()) || [];
  const jsonData = lines.slice(1).map(line => {
      const values = line.split(',').map(value => value.trim());
      return headers.reduce((obj, header, index) => {
          obj[header] = values[index] || '';
          return obj;
      }, {} as Record<string, string>);
  });

  return jsonData as Array<{
      id: string;
      first_name: string;
      last_name: string;
      username: string;
      primary_email_address: string;
      primary_phone_number: string;
      verified_email_addresses: string;
      unverified_email_addresses: string;
      verified_phone_numbers: string;
      unverified_phone_numbers: string;
      totp_secret: string;
      password_digest: string;
      password_hasher: string;
  }>;
}

const exportedUserCSV = await Bun.file("exported_users.csv").text(); // 这是您从 Clerk 下载的文件

async function getClerkUsers(totalUsers: number) {
  const clerkUsers: {
      id: string;
      first_name: string;
      last_name: string;
      username: string;
      image_url: string;
      password_enabled: boolean;
      two_factor_enabled: boolean;
      totp_enabled: boolean;
      backup_code_enabled: boolean;
      banned: boolean;
      locked: boolean;
      lockout_expires_in_seconds: number;
      created_at: number;
      updated_at: number;
      external_accounts: {
          id: string;
          provider: string;
          identification_id: string;
          provider_user_id: string;
          approved_scopes: string;
          email_address: string;
          first_name: string;
          last_name: string;
          image_url: string;
          created_at: number;
          updated_at: number;
      }[]
  }[] = [];
  for (let i = 0; i < totalUsers; i += 500) {
      const response = await fetch(`https://api.clerk.com/v1/users?offset=${i}&limit=${500}`, {
          headers: {
              'Authorization': `Bearer ${process.env.CLERK_SECRET_KEY}`
          }
      });
      if (!response.ok) {
          throw new Error(`Failed to fetch users: ${response.statusText}`);
      }
      const clerkUsersData = await response.json();
      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
      clerkUsers.push(...clerkUsersData as any);
  }
  return clerkUsers;
}


export async function generateBackupCodes(
  secret: string,
) {
  const key = secret;
  const backupCodes = Array.from({ length: 10 })
      .fill(null)
      .map(() => generateRandomString(10, "a-z", "0-9", "A-Z"))
      .map((code) => `${code.slice(0, 5)}-${code.slice(5)}`);
  const encCodes = await symmetricEncrypt({
      data: JSON.stringify(backupCodes),
      key: key,
  });
  return encCodes
}

// 安全转换时间戳为 Date 的辅助函数
function safeDateConversion(timestamp?: number): Date {
  if (!timestamp) return new Date();

  // 将秒转换为毫秒
  const date = new Date(timestamp * 1000);

  // 检查日期是否有效
  if (isNaN(date.getTime())) {
      console.warn(`Invalid timestamp: ${timestamp}, falling back to current date`);
      return new Date();
  }

  // 检查不合理的日期（2000 年之前或 2100 年之后）
  const year = date.getFullYear();
  if (year < 2000 || year > 2100) {
      console.warn(`Suspicious date year: ${year}, falling back to current date`);
      return new Date();
  }

  return date;
}

async function migrateFromClerk() {
  const jsonData = getCSVData(exportedUserCSV);
  const clerkUsers = await getClerkUsers(jsonData.length);
  const ctx = await auth.$context
  const isAdminEnabled = ctx.options?.plugins?.find(plugin => plugin.id === "admin");
  const isTwoFactorEnabled = ctx.options?.plugins?.find(plugin => plugin.id === "two-factor");
  const isUsernameEnabled = ctx.options?.plugins?.find(plugin => plugin.id === "username");
  const isPhoneNumberEnabled = ctx.options?.plugins?.find(plugin => plugin.id === "phone-number");
  for (const user of jsonData) {
      const { id, first_name, last_name, username, primary_email_address, primary_phone_number, verified_email_addresses, unverified_email_addresses, verified_phone_numbers, unverified_phone_numbers, totp_secret, password_digest, password_hasher } = user;
      const clerkUser = clerkUsers.find(clerkUser => clerkUser?.id === id);

      // 创建用户
      const createdUser = await ctx.adapter.create<{
          id: string;
      }>({
          model: "user",
          data: {
              id,
              email: primary_email_address,
              emailVerified: verified_email_addresses.length > 0,
              name: `${first_name} ${last_name}`,
              image: clerkUser?.image_url,
              createdAt: safeDateConversion(clerkUser?.created_at),
              updatedAt: safeDateConversion(clerkUser?.updated_at),
              // # 双因素认证（如果启用了双因素插件）
              ...(isTwoFactorEnabled ? {
                  twoFactorEnabled: clerkUser?.two_factor_enabled
              } : {}),
              // # 管理员（如果启用了管理员插件）
              ...(isAdminEnabled ? {
                  banned: clerkUser?.banned,
                  banExpiresAt: clerkUser?.lockout_expires_in_seconds,
                  role: "user"
              } : {}),
              // # 用户名（如果启用了用户名插件）
              ...(isUsernameEnabled ? {
                  username: username,
              } : {}),
              // # 手机号（如果启用了手机号插件）  
              ...(isPhoneNumberEnabled ? {
                  phoneNumber: primary_phone_number,
                  phoneNumberVerified: verified_phone_numbers.length > 0,
              } : {}),
          },
          forceAllowId: true
      }).catch(async e => {
          return await ctx.adapter.findOne<{
              id: string;
          }>({
              model: "user",
              where: [{
                  field: "id",
                  value: id
              }]
          })
      })
      // 创建外部账户
      const externalAccounts = clerkUser?.external_accounts;
      if (externalAccounts) {
          for (const externalAccount of externalAccounts) {
              const { id, provider, identification_id, provider_user_id, approved_scopes, email_address, first_name, last_name, image_url, created_at, updated_at } = externalAccount;
              if (externalAccount.provider === "credential") {
                  await ctx.adapter.create({
                      model: "account",
                      data: {
                          id,
                          providerId: provider,
                          accountId: externalAccount.provider_user_id,
                          scope: approved_scopes,
                          userId: createdUser?.id,
                          createdAt: safeDateConversion(created_at),
                          updatedAt: safeDateConversion(updated_at),
                          password: password_digest,
                      }
                  })
              } else {
                  await ctx.adapter.create({
                      model: "account",
                      data: {
                          id,
                          providerId: provider.replace("oauth_", ""),
                          accountId: externalAccount.provider_user_id,
                          scope: approved_scopes,
                          userId: createdUser?.id,
                          createdAt: safeDateConversion(created_at),
                          updatedAt: safeDateConversion(updated_at),
                      },
                      forceAllowId: true
                  })
              }
          }
      }

      // 双因素认证
      if (isTwoFactorEnabled) {
          await ctx.adapter.create({
              model: "twoFactor",
              data: {
                  userId: createdUser?.id,
                  secret: totp_secret,
                  backupCodes: await generateBackupCodes(totp_secret)
              }
          })
      }
  }
}

migrateFromClerk()
  .then(() => {
      console.log('Migration completed');
      process.exit(0);
  })
  .catch((error) => {
      console.error('Migration failed:', error);
      process.exit(1);
  });

确保将 process.env.CLERK_SECRET_KEY 替换为您自己的 Clerk 密钥。请根据您的需求自定义脚本。

运行迁移

运行迁移：

bun run script/migrate-clerk.ts # 您可以使用任何您喜欢的方式运行脚本

请确保：

首先在开发环境中测试迁移
监控迁移过程中的任何错误
在继续之前验证 Better Auth 中的迁移数据
在迁移完成之前保持 Clerk 的安装和配置

验证迁移

运行迁移后，通过检查数据库验证所有用户是否已正确迁移。

更新您的组件

现在数据已迁移，您可以开始更新组件以使用 Better Auth。以下是登录组件的示例：

components/auth/sign-in.tsx

import { authClient } from "better-auth/client";

export const SignIn = () => {
  const handleSignIn = async () => {
    const { data, error } = await authClient.signIn.email({
      email: "user@example.com",
      password: "password",
    });
    
    if (error) {
      console.error(error);
      return;
    }
    // 处理成功登录
  };

  return (
    <form onSubmit={handleSignIn}>
      <button type="submit">登录</button>
    </form>
  );
};

更新中间件

将您的 Clerk 中间件替换为 Better Auth 的中间件：

middleware.ts


import { NextRequest, NextResponse } from "next/server";
import { getSessionCookie } from "better-auth/cookies";
export async function middleware(request: NextRequest) {
  const sessionCookie = getSessionCookie(request);
  const { pathname } = request.nextUrl;
  if (sessionCookie && ["/login", "/signup"].includes(pathname)) {
    return NextResponse.redirect(new URL("/dashboard", request.url));
  }
  if (!sessionCookie && pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard", "/login", "/signup"],
};

移除 Clerk 依赖

一旦您确认 Better Auth 一切正常，就可以移除 Clerk：

移除 Clerk

pnpm remove @clerk/nextjs @clerk/themes @clerk/types

额外资源

告别 Clerk，迎接 Better Auth – 完整迁移指南！

总结

恭喜！您已成功从 Clerk 迁移至 Better Auth。

Better Auth 提供了更高的灵活性和更多功能——请务必查阅文档以解锁其全部潜力。

开始使用

概念

身份验证

数据库

集成

插件

指南

参考

On this page