NextAuth.js v5 迁移指南：全面解析与实战教程

前言

NextAuth.js 作为 Next.js 生态中最流行的认证解决方案，其 v5 版本带来了重大架构革新。本文将深入剖析 v5 版本的升级要点，帮助开发者顺利完成迁移工作。我们将从核心变更、新特性解析到具体迁移步骤，全方位解读这次升级。

版本概览

NextAuth.js v5 是一次底层重构，主要变化包括：

1. 架构升级：基于 @auth/core 构建，带来更严格的 OAuth/OIDC 规范兼容性
2. 简化配置：统一配置管理，环境变量自动推断
3. 全栈认证：全新的 auth() 方法统一服务端认证方式
4. 边缘兼容：支持 Edge Runtime 环境运行

环境准备

升级前请确保满足以下条件：

• Next.js 版本 ≥ 14.0
• Node.js 版本 ≥ 16.0

安装 v5 版本：

npm install next-auth@beta

核心变更详解

1. 配置体系重构

v5 版本彻底改变了配置管理方式，采用中心化配置模式：

// 新建 auth.ts 在项目根目录
import NextAuth from "next-auth"
import GitHub from "next-auth/providers/github"

export const { auth, handlers, signIn, signOut } = NextAuth({
  providers: [GitHub],
})

关键变化：

• 配置从 API 路由迁移到根目录
• 导出可直接使用的认证方法
• 旧版 API 路由简化为仅处理 HTTP 方法

2. 认证方式统一

v5 引入了革命性的 auth() 方法，统一了各种场景下的认证方式：

使用场景	v4 方式	v5 方式
服务端组件	getServerSession	auth()
中间件	withAuth 包装器	auth 导出
API 路由	getServerSession/getToken	auth(req, res)
getServerSideProps	getServerSession/getToken	auth(context)

3. 适配器变更

数据库适配器包命名空间从 @next-auth 变更为 @auth：

# 旧版
npm install @next-auth/prisma-adapter

# 新版
npm install @auth/prisma-adapter

注意：数据库 Schema 保持兼容，仅 OAuth 1.0 相关字段可移除。

迁移实战指南

1. 服务端组件迁移

// app/page.tsx
- import { authOptions } from "pages/api/auth/[...nextauth]"
- import { getServerSession } from "next-auth/next"
+ import { auth } from "@/auth"

export default async function Page() {
-  const session = await getServerSession(authOptions)
+  const session = await auth()
  return <p>Welcome {session?.user.name}!</p>
}

2. 中间件迁移

// middleware.ts
- export { default } from "next-auth/middleware"
+ export { auth as middleware } from "@/auth"

高级用法：

import { auth } from "@/auth"

export default auth((req) => {
  // 使用 req.auth 访问认证信息
})

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
}

3. API 路由处理

// pages/api/example.ts
- import { getServerSession } from "next-auth/next"
- import { authOptions } from "pages/api/auth/[...nextauth]"
+ import { auth } from "@/auth"

export default async function handler(req, res) {
-  const session = await getServerSession(req, res, authOptions)
+  const session = await auth(req, res)
  if (session) return res.json("Success")
  return res.status(401).json("Unauthorized")
}

边缘兼容性方案

当使用不兼容 Edge 的数据库适配器时，可采用配置分离方案：

1. 创建基础配置：

// auth.config.ts
import GitHub from "next-auth/providers/github"
import type { NextAuthConfig } from "next-auth"

export default { providers: [GitHub] } satisfies NextAuthConfig

2. 主配置文件：

// auth.ts
import NextAuth from "next-auth"
import { PrismaAdapter } from "@auth/prisma-adapter"
import authConfig from "./auth.config"

export const { auth, handlers } = NextAuth({
  adapter: PrismaAdapter(prisma),
  session: { strategy: "jwt" },
  ...authConfig,
})

3. 中间件专用配置：

// middleware.ts
import authConfig from "./auth.config"
import NextAuth from "next-auth"

export const { auth: middleware } = NextAuth(authConfig)

环境变量最佳实践

v5 优化了环境变量处理：

• 统一使用 AUTH_ 前缀（弃用 NEXTAUTH_）
• 支持自动推断：AUTH_GITHUB_ID 和 AUTH_GITHUB_SECRET 会自动应用
• AUTH_URL 在多数场景下可省略
• AUTH_SECRET 成为唯一必需变量

TypeScript 类型变更

主要类型调整：

• NextAuthOptions 重命名为 NextAuthConfig
• 核心类型统一从 @auth/core/types 导出
• 适配器类型从框架包的 /adapters 路径导出

常见问题解答

Q：为什么我的 OAuth 提供商突然不工作了？ A：v5 严格遵循 OAuth 规范，部分非标准实现可能需要调整。建议检查提供商的 issue 列表。

Q：如何保持会话有效期自动续期？ A：只要在调用 auth() 时传入 res 对象（如在 API 路由中），会话有效期就会自动续期。

Q：Edge Runtime 下如何使用数据库适配器？ A：目前多数 ORM 不兼容 Edge，建议采用 JWT 策略或上述的配置分离方案。

升级建议

1. 先在小规模项目或开发环境测试迁移
2. 重点关注自定义提供商的兼容性
3. 利用 TypeScript 类型检查捕获不兼容的 API
4. 逐步迁移，不必一次性替换所有认证代码

结语

NextAuth.js v5 通过简化的 API 设计和更强的规范兼容性，为开发者带来了更优秀的认证体验。本文涵盖的迁移指南将帮助您平稳过渡到新版本。如遇到特殊问题，建议查阅详细的错误日志和社区讨论。