跳转到内容
构建您的应用程序升级版本 15

版本 15

从 14 升级到 15

要更新到 Next.js 版本 15，可以使用 upgrade 代码修改器

终端
npx @next/codemod@canary upgrade

如果您更喜欢手动执行此操作，请确保您安装的是最新的 Next 和 React RC，例如：

终端
npm i next@canary react@rc react-dom@rc eslint-config-next@rc

需要注意的是

  • 如果您看到 peer 依赖项警告，您可能需要将 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 钩子在 React 19 中仍然可用，但已被弃用，并将在未来的版本中删除。建议使用 useActionState，它包含额外的属性，例如直接读取 pending 状态。了解更多。
  • useFormStatus 现在包含额外的键，例如 data、method 和 action。如果您没有使用 React 19，则只有 pending 键可用。了解更多。
  • 在React 19 升级指南中阅读更多信息。

异步请求 API（重大变更）

以前依赖运行时信息的同步动态 API 现在是**异步**的

为了减轻迁移的负担，我们提供了一个代码修改器来自动化该过程，并且可以临时同步访问 API。

cookies 推荐的异步用法 
import { cookies } from 'next/headers'
 
// Before
const cookieStore = cookies()
const token = cookieStore.get('token')
 
// After
const cookieStore = await cookies()
const token = cookieStore.get('token')

临时同步用法
app/page.tsx
import { cookies, type UnsafeUnwrappedCookies } from 'next/headers'
 
// Before
const cookieStore = cookies()
const token = cookieStore.get('token')
 
// After
const cookieStore = cookies() as unknown as UnsafeUnwrappedCookies
// will log a warning in dev
const token = cookieStore.get('token')

headers 推荐的异步用法 
import { headers } from 'next/headers'
 
// Before
const headersList = headers()
const userAgent = headersList.get('user-agent')
 
// After
const headersList = await headers()
const userAgent = headersList.get('user-agent')

临时同步用法
app/page.tsx
import { headers, type UnsafeUnwrappedHeaders } from 'next/headers'
 
// Before
const headersList = headers()
const userAgent = headersList.get('user-agent')
 
// After
const headersList = headers() as unknown as UnsafeUnwrappedHeaders
// will log a warning in dev
const userAgent = headersList.get('user-agent')

draftMode 推荐的异步用法 
import { draftMode } from 'next/headers'
 
// Before
const { isEnabled } = draftMode()
 
// After
const { isEnabled } = await draftMode()

临时同步用法
app/page.tsx
import { draftMode, type UnsafeUnwrappedDraftMode } from 'next/headers'
 
// Before
const { isEnabled } = draftMode()
 
// After
// will log a warning in dev
const { isEnabled } = draftMode() as unknown as UnsafeUnwrappedDraftMode

params 和 searchParams 异步布局
app/layout.tsx
// Before
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
}
 
// After
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
// Before
type Params = { slug: string }
 
export default function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}
 
// After
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
// Before
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
}
 
// After
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'
 
// Before
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
}
 
// After
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
}
// Before
export default function Page({ params, searchParams }) {
  const { slug } = params
  const { query } = searchParams
}
 
// After
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
// Before
type Params = { slug: string }
 
export async function GET(request: Request, segmentData: { params: Params }) {
  const params = segmentData.params
  const slug = params.slug
}
 
// After
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
// Before
export async function GET(request, segmentData) {
  const params = segmentData.params
  const slug = params.slug
}
 
// After
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://...') // Not Cached
  const b = await fetch('https://...', { cache: 'force-cache' }) // Cached
 
  // ...
}

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

app/layout.js
// Since this is the root layout, all fetch requests in the app
// that don't set their own cache option will be cached.
export const fetchCache = 'default-cache'
 
export default async function RootLayout() {
  const a = await fetch('https://...') // Cached
  const b = await fetch('https://...', { cache: 'no-store' }) // Not cached
 
  // ...
}

路由处理程序 路由处理程序 中不再默认缓存。要选择将 GET 方法缓存，您可以在路由处理程序文件中使用 路由配置选项，例如 export const dynamic = 'force-static'。

app/api/route.js
export const dynamic = 'force-static'
 
export async function GET() {}

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

要选择将页面段缓存，可以使用 staleTimes 配置选项

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

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

next/font next/font。可以使用 codemod 安全、自动地重命名您的导入。

app/layout.js
// Before
import { Inter } from '@next/font/google'
 
// After
import { Inter } from 'next/font/google'

bundlePagesRouterDependencies
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    bundlePagesExternals: true,
  },
 
  // After
  bundlePagesRouterDependencies: true,
}
 
module.exports = nextConfig

serverExternalPackages
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Before
  experimental: {
    serverComponentsExternalPackages: ['package-name'],
  },
 
  // After
  serverExternalPackages: ['package-name'],
}
 
module.exports = nextConfig

速度洞察 Vercel 速度洞察快速入门 指南进行操作。

NextRequest 地理位置 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)
 
  // ...
}