NextAuth.js v5迁移指南与实战示例

原创

用户11764306

发布于 2025-08-10 19:39:14

2030

NextAuth.js v5迁移指南与实战示例

为何迁移到NextAuth.js v5？

更好的TypeScript支持：全面提升类型安全性
统一API：跨框架一致性接口
增强安全性：改进的会话管理和CSRF防护
框架无关：支持Next.js、SvelteKit、SolidStart等
开发者体验优化：更清晰的错误信息和调试支持

准备工作

⚠️ 重要提示：NextAuth.js v5仍处于测试阶段。生产环境应用需谨慎测试。

当前环境检查

# 检查当前NextAuth版本
npm list next-auth

# 示例项目使用版本
"next-auth": "^4.24.7"

第一步：安装与依赖管理

移除旧包

npm uninstall next-auth
npm uninstall @next-auth/prisma-adapter  # 如果使用Prisma

安装NextAuth v5

npm install next-auth@beta
npm install @auth/prisma-adapter  # 新版Prisma适配器

更新package.json

{
  "dependencies": {
    "next-auth": "5.0.0-beta.25",
    "@auth/prisma-adapter": "^2.6.0",
    "prisma": "^5.22.0",
    "@prisma/client": "^5.22.0"
  }
}

第二步：配置迁移

v4配置示例

// pages/api/auth/[...nextauth].ts
import NextAuth from 'next-auth'
import GoogleProvider from 'next-auth/providers/google'
import CredentialsProvider from 'next-auth/providers/credentials'
import { PrismaAdapter } from '@next-auth/prisma-adapter'
import { prisma } from '@/lib/prisma'
import bcrypt from 'bcryptjs'

export default NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    // ...其他配置
  ]
})

v5配置示例

// app/api/auth/[...nextauth]/route.ts
import NextAuth from 'next-auth'
import Google from 'next-auth/providers/google'
import Credentials from 'next-auth/providers/credentials'
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/prisma'
import bcrypt from 'bcryptjs'

const handler = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
    // ...其他配置
  ]
});

export { handler as GET, handler as POST }

第三步：环境变量更新

新环境变量要求

# .env.local
# v5使用AUTH_SECRET替代NEXTAUTH_SECRET
AUTH_SECRET=your-secret-key-here
AUTH_URL=http://localhost:3000

# Google OAuth (保持不变)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

第四步：类型定义更新

v5类型定义示例

// types/auth.d.ts
import { DefaultSession } from 'next-auth'

declare module 'next-auth' {
  interface Session {
    user: {
      id: string
      roleId: number
    } & DefaultSession['user']
  }

  interface User {
    roleId?: number  // OAuth用户设为可选
  }
}

第五步：客户端使用更新

v5客户端示例

// app/layout.tsx
import { SessionProvider } from 'next-auth/react'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <SessionProvider>{children}</SessionProvider>
      </body>
    </html>
  )
}

第六步：服务端使用更新

v5服务端示例

// lib/auth.ts
import NextAuth from 'next-auth'
import Google from 'next-auth/providers/google'
import { PrismaAdapter } from '@auth/prisma-adapter'
import { prisma } from '@/lib/prisma'

export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: PrismaAdapter(prisma),
  providers: [
    Google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  // ...其他配置
})

第七步：中间件更新

v5中间件示例

import { auth } from '@/lib/auth'
import { NextResponse } from 'next/server'

export default auth((req) => {
  const { nextUrl } = req
  const isLoggedIn = !!req.auth

  // 保护管理员路由
  if (nextUrl.pathname.startsWith('/admin')) {
    if (!isLoggedIn || req.auth?.user?.roleId !== 4) {
      return NextResponse.redirect(new URL('/auth/signin', nextUrl))
    }
  }

  return NextResponse.next()
})

第八步：数据库架构考虑

v5 Prisma架构示例

model Account {
  id                String  @id @default(cuid())
  userId            String  @map("user_id")
  type              String
  provider          String
  providerAccountId String  @map("provider_account_id")
  // ...其他字段
}

model Session {
  id           String   @id @default(cuid())
  sessionToken String   @unique @map("session_token")
  userId       String   @map("user_id")
  expires      DateTime
  // ...其他关系
}

model User {
  id            String    @id @default(cuid())
  name          String?
  email         String    @unique
  password      String?   // 凭证验证使用
  emailVerified DateTime? @map("email_verified")
  // ...其他字段
}

第九步：迁移测试

测试清单

// test/auth.test.ts
import { describe, it, expect } from 'vitest'
import { auth } from '@/lib/auth'

describe('NextAuth v5迁移测试', () => {
  it('应处理OAuth登录', async () => {
    // 测试OAuth流程
  })
  // ...其他测试用例
})

常见迁移问题与解决方案

问题1：凭证验证的会话策略

解决方案：使用JWT策略

export const { handlers, auth } = NextAuth({
  session: { strategy: 'jwt' }, // 凭证验证必需
  providers: [
    Credentials({
      // ...凭证配置
    }),
  ],
})