NNext.js 中文网 GitHub

如何升级到版本 15

将你的 Next.js 应用程序从版本 14 升级到 15。

从 14 升级到 15#

要更新到 Next.js 版本 15,你可以使用 upgrade codemod:

bash · pnpm
pnpm dlx @next/codemod@canary upgrade latest
bash · npm
npx @next/codemod@canary upgrade latest
bash · yarn
yarn dlx @next/codemod@canary upgrade latest
bash · bun
bunx @next/codemod@canary upgrade latest

如果你更愿意手动操作,请确保安装的是最新的 Next 和 React 版本:

bash · pnpm
pnpm add next@latest react@latest react-dom@latest eslint-config-next@latest
bash · npm
npm install next@latest react@latest react-dom@latest eslint-config-next@latest
bash · yarn
yarn add next@latest react@latest react-dom@latest eslint-config-next@latest
bash · bun
bun add next@latest react@latest react-dom@latest eslint-config-next@latest

小知识:

  • 如果你看到 peer dependencies 警告,可能需要将 react 和 react-dom 更新到建议的版本,或使用 --force 或 --legacy-peer-deps 标志忽略该警告。一旦 Next.js 15 和 React 19 都稳定下来,就不再需要这样做了。

React 19#

  • react 和 react-dom 的最低版本现在为 19。
  • Pages Router 同时支持 React 18 和 React 19,因此将 react 和 react-dom 升级到 19 是可选的。
  • useFormState 已被 useActionState 取代。useFormState hook 在 React 19 中仍然可用,但已弃用,将在未来版本中移除。推荐使用 useActionState,它包含额外特性,例如直接读取 pending 状态。了解更多。
  • useFormStatus 现在包含额外的键,如 data、method 和 action。如果你没有使用 React 19,则只有 pending 键可用。了解更多。
  • 更多内容请参阅 React 19 升级指南。

小知识: 如果你使用 TypeScript,请确保同时将 @types/react 和 @types/react-dom 升级到最新版本。

异步请求 API(破坏性变更)#

以前依赖于请求信息的同步请求时 API 现在变为异步的:

为减轻迁移负担,可以使用 codemod 自动完成该过程,这些 API 暂时仍可以同步方式访问。

cookies#

推荐的异步用法#

tsx
import { cookies } from 'next/headers'

// 之前
const cookieStore = cookies()
const token = cookieStore.get('token')

// 之后
const cookieStore = await cookies()
const token = cookieStore.get('token')

临时同步用法#

app/page.tsx
import { cookies, type UnsafeUnwrappedCookies } from 'next/headers'

// 之前
const cookieStore = cookies()
const token = cookieStore.get('token')

// 之后
const cookieStore = cookies() as unknown as UnsafeUnwrappedCookies
// 在开发环境中会记录一条警告
const token = cookieStore.get('token')
app/page.js
import { cookies } from 'next/headers'

// 之前
const cookieStore = cookies()
const token = cookieStore.get('token')

// 之后
const cookieStore = cookies()
// 在开发环境中会记录一条警告
const token = cookieStore.get('token')

headers#

推荐的异步用法#

tsx
import { headers } from 'next/headers'

// 之前
const headersList = headers()
const userAgent = headersList.get('user-agent')

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

临时同步用法#

app/page.tsx
import { headers, type UnsafeUnwrappedHeaders } from 'next/headers'

// 之前
const headersList = headers()
const userAgent = headersList.get('user-agent')

// 之后
const headersList = headers() as unknown as UnsafeUnwrappedHeaders
// 在开发环境中会记录一条警告
const userAgent = headersList.get('user-agent')
app/page.js
import { headers } from 'next/headers'

// 之前
const headersList = headers()
const userAgent = headersList.get('user-agent')

// 之后
const headersList = headers()
// 在开发环境中会记录一条警告
const userAgent = headersList.get('user-agent')

draftMode#

推荐的异步用法#

tsx
import { draftMode } from 'next/headers'

// 之前
const { isEnabled } = draftMode()

// 之后
const { isEnabled } = await draftMode()

临时同步用法#

app/page.tsx
import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'

// 之前
const { isEnabled } = draftMode()

// 之后
// 在开发环境中会记录一条警告
const { isEnabled } = draftMode() as unknown as UnsafeUnwrappedDraftMode
app/page.js
import { draftMode } from 'next/headers'

// 之前
const { isEnabled } = draftMode()

// 之后
// 在开发环境中会记录一条警告
const { isEnabled } = draftMode()

params & searchParams#

异步布局#

app/layout.tsx
// 之前
type Params = { slug: string }

export function generateMetadata({ params }: { params: Params }) {
  const { slug } = params
}

export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}

// 之后
type Params = Promise<{ slug: string }>

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

export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = await params
}
app/layout.js
// 之前
export function generateMetadata({ params }) {
  const { slug } = params
}

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

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

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

同步布局#

app/layout.tsx
// 之前
type Params = { slug: string }

export default function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}

// 之后
import { use } from 'react'

type Params = Promise<{ slug: string }>

export default function Layout(props: {
  children: React.ReactNode
  params: Params
}) {
  const params = use(props.params)
  const slug = params.slug
}
app/layout.js
// 之前
export default function Layout({ children, params }) {
  const { slug } = params
}

// 之后
import { use } from 'react'
export default async function Layout(props) {
  const params = use(props.params)
  const slug = params.slug
}

异步页面#

app/page.tsx
// 之前
type Params = { slug: string }
type SearchParams = { [key: string]: string | string[] | undefined }

export function generateMetadata({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}

export default async function Page({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}

// 之后
type Params = Promise<{ slug: string }>
type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>

export async function generateMetadata(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}

export default async function Page(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}
app/page.js
// 之前
export function generateMetadata({ params, searchParams }) {
  const { slug } = params
  const { query } = searchParams
}

export default function Page({ params, searchParams }) {
  const { slug } = params
  const { query } = searchParams
}

// 之后
export async function generateMetadata(props) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}

export default async function Page(props) {
  const params = await props.params
  const searchParams = await props.searchParams
  const slug = params.slug
  const query = searchParams.query
}

同步页面#

tsx
'use client'

// 之前
type Params = { slug: string }
type SearchParams = { [key: string]: string | string[] | undefined }

export default function Page({
  params,
  searchParams,
}: {
  params: Params
  searchParams: SearchParams
}) {
  const { slug } = params
  const { query } = searchParams
}

// 之后
import { use } from 'react'

type Params = Promise<{ slug: string }>
type SearchParams = Promise<{ [key: string]: string | string[] | undefined }>

export default function Page(props: {
  params: Params
  searchParams: SearchParams
}) {
  const params = use(props.params)
  const searchParams = use(props.searchParams)
  const slug = params.slug
  const query = searchParams.query
}
jsx
// 之前
export default function Page({ params, searchParams }) {
  const { slug } = params
  const { query } = searchParams
}

// 之后
import { use } from "react"

export default function Page(props) {
  const params = use(props.params)
  const searchParams = use(props.searchParams)
  const slug = params.slug
  const query = searchParams.query
}

Route Handlers#

app/api/route.ts
// 之前
type Params = { slug: string }

export async function GET(request: Request, segmentData: { params: Params }) {
  const params = segmentData.params
  const slug = params.slug
}

// 之后
type Params = Promise<{ slug: string }>

export async function GET(request: Request, segmentData: { params: Params }) {
  const params = await segmentData.params
  const slug = params.slug
}
app/api/route.js
// 之前
export async function GET(request, segmentData) {
  const params = segmentData.params
  const slug = params.slug
}

// 之后
export async function GET(request, segmentData) {
  const params = await segmentData.params
  const slug = params.slug
}

runtime 配置(破坏性变更)#

runtime 段配置以前除了 edge 之外还支持 experimental-edge 值。两种配置含义相同,为简化选项,现在如果使用 experimental-edge 会报错。要解决此问题,请将 runtime 配置更新为 edge。可以使用 codemod 自动完成此操作。

fetch 请求#

fetch 请求现在默认不再被缓存。

要让特定的 fetch 请求选择缓存,可以传入 cache: 'force-cache' 选项。

app/layout.js
export default async function RootLayout() {
  const a = await fetch('https://...') // 未缓存
  const b = await fetch('https://...', { cache: 'force-cache' }) // 已缓存

  // ...
}

要让某个布局或页面中的所有 fetch 请求选择缓存,可以使用 export const fetchCache = 'default-cache' 段配置选项。如果单个 fetch 请求指定了 cache 选项,则以该选项为准。

app/layout.js
// 由于这是根布局,应用中所有
// 未设置自身 cache 选项的 fetch 请求都将被缓存。
export const fetchCache = 'default-cache'

export default async function RootLayout() {
  const a = await fetch('https://...') // 已缓存
  const b = await fetch('https://...', { cache: 'no-store' }) // 未缓存

  // ...
}

Route Handlers#

Route Handlers中的 GET 函数现在默认不再被缓存。要让 GET 方法选择缓存,可以在 Route Handler 文件中使用 route 配置选项,例如 export const dynamic = 'force-static'。

app/api/route.js
export const dynamic = 'force-static'

export async function GET() {}

Client Cache#

通过 <Link> 或 useRouter 在页面间导航时,page 段不再从 Client Cache 中复用。不过,在浏览器前进/后退导航以及共享布局时,它们仍会被复用。

要让 page 段选择缓存,可以使用 staleTimes 配置选项:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,
      static: 180,
    },
  },
}

module.exports = nextConfig

Layouts和加载状态在导航时仍会被缓存和复用。

next/font#

@next/font 包已被移除,取而代之的是内置的 next/font。可以使用 codemod 安全、自动地重命名你的导入。

app/layout.js
// 之前
import { Inter } from '@next/font/google'

// 之后
import { Inter } from 'next/font/google'

bundlePagesRouterDependencies#

experimental.bundlePagesExternals 现已稳定,并更名为 bundlePagesRouterDependencies。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 之前
  experimental: {
    bundlePagesExternals: true,
  },

  // 之后
  bundlePagesRouterDependencies: true,
}

module.exports = nextConfig

serverExternalPackages#

experimental.serverComponentsExternalPackages 现已稳定,并更名为 serverExternalPackages。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 之前
  experimental: {
    serverComponentsExternalPackages: ['package-name'],
  },

  // 之后
  serverExternalPackages: ['package-name'],
}

module.exports = nextConfig

Speed Insights#

Speed Insights 的自动插桩已在 Next.js 15 中移除。

要继续使用 Speed Insights,请遵循 Vercel Speed Insights 快速入门指南。

NextRequest 地理位置#

NextRequest 上的 geo 和 ip 属性已被移除,因为这些值由你的托管服务商提供。可以使用 codemod 自动完成此迁移。

如果你使用 Vercel,也可以改用 @vercel/functions 中的 geolocation 和 ipAddress 函数:

middleware.ts
import { geolocation } from '@vercel/functions'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const { city } = geolocation(request)

  // ...
}
middleware.ts
import { ipAddress } from '@vercel/functions'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  const ip = ipAddress(request)

  // ...
}

故障排查#

升级到 React 19 后安装失败#

  • 如果其他包的 peer dependencies 不接受 React 19,请将 react、react-dom、它们的类型以及 react-is(如果存在)回退到之前的版本,前提是目标 Next.js 版本和 router 支持这些版本。
  • 恢复或移除升级过程中在 package.json 或 pnpm-workspace.yaml 中添加的 React 类型覆盖(overrides)或 resolutions。
  • 如果安装过程中断了升级命令,请使用 --skip-react-upgrade 重试完全相同的目标,以保留已修复的依赖项。如果 Next.js 已与目标版本匹配,请安装依赖并单独运行任何跳过的 codemod。运行应用的检查。

升级到 ESLint 9 后安装失败#

  • 如果其他包的 peer dependencies 不接受 ESLint 9,请将 eslint、eslint-config-next 和 @next/eslint-plugin-next(如果存在)恢复到之前兼容的版本,并恢复之前的 lint 配置。
  • 如果安装过程中断了升级命令,请使用 --skip-eslint-upgrade 重试完全相同的目标,以保留已修复的依赖项。如果 Next.js 已与目标版本匹配,请安装依赖并单独运行任何跳过的 codemod。手动完成任何必需的 lint 迁移,然后运行应用的 lint 检查。

检查迁移清单#

在应用与你的应用相关的更改后,在认为迁移完成之前,请检查以下待办事项:

  • React 依赖项和类型满足应用所用 router 的 React 19 要求。
  • 字体导入使用 next/font 而非 @next/font。
  • 现有的 bundlePagesExternals 和 serverComponentsExternalPackages 设置使用文档中记录的稳定名称,同时保留包配置。
  • NextRequest 的 geo 和 ip 使用方针对实际的托管服务商使用合适的来源。
  • 依赖 Speed Insights 自动插桩的应用,如果仍需要该功能,已完成显式集成。
  • 应用支持的检查及受影响的运行时行为均已通过。仍有必需的失败项意味着迁移尚未完成。
  • 异步请求 API 的访问(包括受影响的工具函数和调用方)已完成迁移。请处理 codemod 的错误注释和 UnsafeUnwrapped 类型转换,而不是将它们视为已修复。
  • 路由段的 runtime 设置不再使用 experimental-edge。
Next.js 中文网