版本 15

从 14 升级到 15

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

Terminal

npx @next/codemod@canary upgrade latest

如果你更倏手动升级，确保安装最新的 Next.js 和 React RC 版本：

Terminal

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

值得注意的是：

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

如果你正在使用 TypeScript，你需要临时覆盖 React 类型。查看 React 19 RC 升级指南获取更多信息。

React 19

react 和 react-dom 的最低版本现在是 19。
useFormState 已被 useActionState 替代。useFormState hook 在 React 19 中仍然可用，但它已被废弃，并将在未来版本中移除。推荐使用 useActionState，它包含额外的属性，比如直接读取 pending 状态。了解更多。
useFormStatus 现在包含额外的键值，如 data、method 和 action。如果你没有使用 React 19，则只有 pending 键可用。了解更多。
在 React 19 升级指南中了解更多。

异步请求 API（重大变更）

之前依赖运行时信息的同步动态 API 现在变成了异步：

cookies
headers
draftMode
params 在 layout.js、page.js、route.js、default.js、opengraph-image、twitter-image、icon 和 apple-icon 中。
searchParams 在 page.js 中

为了减轻迁移负担，我们提供了一个 codemod 来自动化这个过程，并且这些 API 可以暂时以同步方式访问。

`cookies`

临时的同步用法

app/page.tsx

TypeScript

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')

`headers`

临时的同步用法

app/page.tsx

TypeScript

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')

`draftMode`

临时的同步用法

app/page.tsx

TypeScript

import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'
 
// 之前
const { isEnabled } = draftMode()
 
// 之后
// 在开发环境下会显示警告
const { isEnabled } = draftMode() as unknown as UnsafeUnwrappedDraftMode

`params` & `searchParams`

异步布局

app/layout.tsx

TypeScript

// 之前
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.tsx

TypeScript

// 之前
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/page.tsx

TypeScript

// 之前
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
}

同步页面

'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 = { [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
}

// 之前
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
}

路由处理程序

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

// 由于这是根布局，应用中所有未设置自己的缓存选项的 fetch 请求都将被缓存。
export const fetchCache = 'default-cache'
 
export default async function RootLayout() {
  const a = await fetch('https://...') // 缓存
  const b = await fetch('https://...', { cache: 'no-store' }) // 不缓存
 
  // ...
}

路由处理程序

路由处理程序中的 GET 函数默认不再缓存。要将 GET 方法选择性地加入缓存，你可以在路由处理程序文件中使用路由配置选项，比如 export const dynamic = 'force-static'。

app/api/route.js

export const dynamic = 'force-static'
 
export async function GET() {}

客户端路由缓存

通过 <Link> 或 useRouter 在页面间导航时，页面段不再从客户端路由缓存中重用。但是，它们在浏览器后退和前进导航以及共享布局时仍然会被重用。

要将页面段选择性地加入缓存，你可以使用 staleTimes 配置选项：

next.config.js

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

布局和加载状态在导航时仍然会被缓存和重用。

`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

Next.js 15 中移除了 Speed Insights 的自动检测。

要继续使用 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)
 
  // ...
}

版本 15

从 14 升级到 15

React 19

异步请求 API（重大变更）

`cookies`

推荐的异步用法

临时的同步用法

`headers`

推荐的异步用法

临时的同步用法

`draftMode`

推荐的异步用法

临时的同步用法

`params` & `searchParams`

异步布局

同步布局

异步页面

同步页面

路由处理程序

`runtime` 配置（重大变更）

`fetch` 请求

路由处理程序

客户端路由缓存

`next/font`

bundlePagesRouterDependencies

serverExternalPackages

Speed Insights

`NextRequest` 地理位置