Next.js 15 升级指南：从版本 14 迁移到 15 的完整教程

Next.js 15 带来了多项重要更新和改进，本文将详细介绍如何从版本 14 平滑升级到 15，并解析所有需要注意的变更点。

升级准备

升级到 Next.js 15 有两种主要方式：

1. 使用 codemod 自动升级（推荐）

npx @next/codemod@canary upgrade latest

2. 手动升级

npm i next@latest react@latest react-dom@latest eslint-config-next@latest

重要提示：如果遇到 peer dependencies 警告，可能需要更新 react 和 react-dom 到建议版本，或使用 --force 或 --legacy-peer-deps 标志忽略警告。

React 19 兼容性变更

Next.js 15 要求 React 19 作为最低版本，带来了几个重要变化：

1. useFormState 替换：useFormState 已被 useActionState 取代，虽然目前仍可用但已被标记为废弃
2. useFormStatus 扩展：现在包含 data、method 和 action 等新属性
3. TypeScript 用户注意：需要同时升级 @types/react 和 @types/react-dom

异步 API 变更（重大变更）

Next.js 15 将多个动态 API 从同步改为异步，这是最需要注意的变更之一：

受影响的 API 列表

• cookies()
• headers()
• draftMode()
• params（在 layout.js、page.js 等文件中）
• searchParams（在 page.js 中）

各 API 迁移示例

cookies() 使用方式变化

推荐异步用法：

const cookieStore = await cookies()
const token = cookieStore.get('token')

临时同步用法（不推荐）：

const cookieStore = cookies() as unknown as UnsafeUnwrappedCookies
const token = cookieStore.get('token') // 开发环境会有警告

headers() 使用方式变化

推荐异步用法：

const headersList = await headers()
const userAgent = headersList.get('user-agent')

draftMode() 使用方式变化

推荐异步用法：

const { isEnabled } = await draftMode()

布局和页面中的 params/searchParams

异步布局示例

export async function generateMetadata({ params }) {
  const { slug } = await params
}

export default async function Layout({ children, params }) {
  const { slug } = await params
}

同步布局示例（使用 React 的 use）

import { use } from 'react'

export default function Layout(props) {
  const params = use(props.params)
  const slug = params.slug
}

路由处理器变更

GET 方法默认不再缓存，需要通过配置显式启用：

export const dynamic = 'force-static'

export async function GET() {}

客户端路由缓存行为变更

通过 <Link> 或 useRouter 导航时，页面段不再从客户端路由缓存中重用。可以通过配置 staleTimes 来调整：

// next.config.js
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,    // 动态路由缓存30秒
      static: 180,    // 静态路由缓存180秒
    },
  },
}

字体系统变更

@next/font 包已被移除，统一使用内置的 next/font：

// 替换前
import { Inter } from '@next/font/google'

// 替换后
import { Inter } from 'next/font/google'

配置项稳定化

多个实验性配置已转为稳定版：

1. bundlePagesExternals → bundlePagesRouterDependencies
2. serverComponentsExternalPackages → serverExternalPackages

其他重要变更

1. fetch 请求默认不再缓存：需要显式设置 cache: 'force-cache'
2. Speed Insights 自动检测移除：需要手动设置
3. NextRequest 地理定位属性移除：geo 和 ip 属性已移除

升级建议

1. 首先使用 codemod 自动处理大部分变更
2. 仔细检查异步 API 的变更，特别是 cookies 和 headers 的使用
3. 测试路由缓存行为是否符合预期
4. 更新所有相关类型定义
5. 全面测试应用功能，特别是依赖上述变更 API 的部分

通过遵循本指南，您可以顺利完成 Next.js 15 的升级，并充分利用新版本带来的性能改进和新特性。