跳到内容
指南升级版本 16

如何升级到版本 16

从 15 升级到 16

将 AI 代理与 Next.js DevTools MCP 配合使用

如果您正在使用支持模型上下文协议 (MCP)的 AI 编码助手，您可以使用 Next.js DevTools MCP 来自动化升级过程和迁移任务。

设置

将以下配置添加到您的 MCP 客户端，例如

{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

有关更多信息，请访问 npm 上的 next-devtools-mcp 包，以配置您的 MCP 客户端。

注意：使用next-devtools-mcp@latest可确保您的 MCP 客户端始终使用最新版本的 Next.js DevTools MCP 服务器。

示例提示

配置完成后，您可以使用自然语言提示来升级您的 Next.js 应用程序

升级到 Next.js 16

连接到您的编码代理，然后提示

Next Devtools, help me upgrade my Next.js app to version 16

迁移到缓存组件（升级到 v16 后）

连接到您的编码代理，然后提示

Next Devtools, migrate my Next.js app to cache components

使用 Codemod

要更新到 Next.js 版本 16，您可以使用 upgrade codemod

终端
npx @next/codemod@canary upgrade latest

此 codemod 能够

  • 更新 next.config.js 以使用新的 turbopack 配置
  • 从 next lint 迁移到 ESLint CLI
  • 从已弃用的 middleware 约定迁移到 proxy
  • 从已稳定的 API 中删除 unstable_ 前缀
  • 从页面和布局中删除 experimental_ppr 路由段配置

如果您喜欢手动操作，请安装最新的 Next.js 和 React 版本

终端
npm install next@latest react@latest react-dom@latest

如果您正在使用 TypeScript，请确保您也将 @types/react 和 @types/react-dom 升级到最新版本。

Node.js 运行时和浏览器支持

要求更改 / 详情
Node.js 20.9+最低版本现在是 20.9.0 (LTS)；Node.js 18 不再受支持
TypeScript 5+最低版本现在是 5.1.0
浏览器Chrome 111+、Edge 111+、Firefox 111+、Safari 16.4+

默认使用 Turbopack

从 Next.js 16 开始，Turbopack 稳定，并且默认与 next dev 和 next build 一起使用

以前您必须使用 --turbopack 或 --turbo 启用 Turbopack。

package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start"
  }
}

这不再是必需的。您可以更新您的 package.json 脚本

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

如果您的项目有 自定义 webpack 配置并且您运行 next build（现在默认使用 Turbopack），则构建将失败以防止配置错误。

您有几种不同的方法来解决这个问题

  • 仍然使用 Turbopack：使用 next build --turbopack 进行构建，并忽略您的 webpack 配置。
  • 完全切换到 Turbopack：将您的 webpack 配置迁移到 Turbopack 兼容选项。
  • 继续使用 Webpack：使用 --webpack 标志选择退出 Turbopack 并使用 Webpack 进行构建。

提示：如果您因为找到 webpack 配置而导致构建失败，但您自己并未定义该配置，则很可能是某个插件添加了 webpack 选项

退出 Turbopack

如果您需要继续使用 Webpack，您可以使用 --webpack 标志选择退出。例如，在开发中使用 Turbopack，但在生产构建中使用 Webpack

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "start": "next start"
  }
}

我们建议在开发和生产中使用 Turbopack。如果您无法切换到 Turbopack，请在此 讨论中提交评论。

Turbopack 配置位置

experimental.turbopack 配置已脱离实验阶段。

next.config.ts
import type { NextConfig } from 'next'
 
// Next.js 15 - experimental.turbopack
const nextConfig: NextConfig = {
  experimental: {
    turbopack: {
      // options
    },
  },
}
 
export default nextConfig

您可以将其用作顶级 turbopack 选项

next.config.ts
import type { NextConfig } from 'next'
 
// Next.js 16 - turbopack at the top level of nextConfig
const nextConfig: NextConfig = {
  turbopack: {
    // options
  },
}
 
export default nextConfig

请务必查阅 Turbopack 配置选项。Next.js 16 引入了各种改进和新选项，例如

解决别名回退

在某些项目中，客户端代码可能会导入包含 Node.js 原生模块的文件。这将导致 Module not found: Can't resolve 'fs' 类型的错误。

发生这种情况时，您应该重构您的代码，以便您的客户端捆绑包不引用这些 Node.js 原生模块。

然而，在某些情况下，这可能无法实现。在 Webpack 中，resolve.fallback 选项通常用于消除此错误。Turbopack 提供了类似的选项，使用 turbopack.resolveAlias。在这种情况下，告诉 Turbopack 在浏览器请求 fs 时加载一个空模块。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      fs: {
        browser: './empty.ts', // We recommend to fix code imports before using this method
      },
    },
  },
}
 
export default nextConfig

最好重构您的模块，以便客户端代码永远不会从使用 Node.js 原生模块的模块中导入。

Sass node_modules 导入

Turbopack 完全支持从 node_modules 导入 Sass 文件。请注意，虽然 Webpack 允许使用旧版波浪号 (~) 前缀，但 Turbopack 不支持此语法。

在 Webpack 中

styles/globals.scss
@import '~bootstrap/dist/css/bootstrap.min.css';

在 Turbopack 中

styles/globals.scss
@import 'bootstrap/dist/css/bootstrap.min.css';

如果无法更改导入，可以使用 turbopack.resolveAlias。例如

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      '~*': '*',
    },
  },
}
 
export default nextConfig

Turbopack 文件系统缓存（测试版）

Turbopack 现在支持在开发中使用文件系统缓存，在每次运行之间将编译器工件存储在磁盘上，从而显著加快重启时的编译时间。

在您的配置中启用文件系统缓存

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    turbopackFileSystemCacheForDev: true,
  },
}
 
export default nextConfig

异步请求 API（重大更改）

版本 15 引入了异步请求 API作为重大更改，具有临时同步兼容性。

从 Next.js 16 开始，完全移除了同步访问。这些 API 只能异步访问。

使用 codemod 迁移到异步动态 API。

迁移异步动态 API 的类型

为了帮助迁移到异步 params 和 searchParams，您可以运行 npx next typegen 自动生成这些全局可用的类型助手

提示：typegen 在 Next.js 15.5 中引入

这简化了对新异步 API 模式的类型安全迁移，并使您能够完全类型安全地更新组件，例如

/app/blog/[slug]/page.tsx
export default async function Page(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params
  const query = await props.searchParams
  return <h1>Blog Post: {slug}</h1>
}

此方法使您能够完全类型安全地直接在页面中访问 props.params（包括 slug）和 searchParams。

icon 和 open-graph Image 的异步参数（重大更改）

传递给 opengraph-image、twitter-image、icon 和 apple-icon 中的图像生成函数的 prop 现在是 Promise。

在以前的版本中，Image（图像生成函数）和 generateImageMetadata 都接收一个 params 对象。generateImageMetadata 返回的 id 作为字符串传递给图像生成函数。

app/shop/[slug]/opengraph-image.js
// Next.js 15 - synchronous params access
export function generateImageMetadata({ params }) {
  const { slug } = params
  return [{ id: '1' }, { id: '2' }]
}
 
// Next.js 15 - synchronous params and id access
export default function Image({ params, id }) {
  const slug = params.slug
  const imageId = id // string
  // ...
}

从 Next.js 16 开始，为了与异步请求 API 更改保持一致，这些也都是异步的。

app/shop/[slug]/opengraph-image.js
// Next.js 16 - asynchronous params access
export async function generateImageMetadata({ params }) {
  const { slug } = await params
  return [{ id: '1' }, { id: '2' }]
}
 
// Next.js 16 - asynchronous params and id access
export default async function Image({ params, id }) {
  const { slug } = await params // params now async
  const imageId = await id // id is now Promise<string> when using generateImageMetadata
  // ...
}

React 19.2

Next.js 16 中的 App Router 使用最新的 React Canary 版本，其中包括新发布的 React 19.2 功能和正在逐步稳定的其他功能。亮点包括

  • 视图过渡：动画在过渡或导航内部更新的元素
  • useEffectEvent：将 Effects 中的非反应式逻辑提取到可重用的 Effect Event 函数中
  • 活动：通过使用 display: none 隐藏 UI 同时保持状态并清理 Effects 来渲染“后台活动”

在 React 19.2 公告中了解更多信息。

React 编译器支持

在 React Compiler 1.0 发布后，Next.js 16 中对 React Compiler 的内置支持现已稳定。React Compiler 自动记忆组件，通过零手动代码更改减少不必要的重新渲染。

reactCompiler 配置选项已从 experimental 提升为稳定版。由于我们仍在收集不同应用程序类型的构建性能数据，因此默认情况下未启用此选项。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  reactCompiler: true,
}
 
export default nextConfig

安装最新版本的 React Compiler 插件

终端
npm install babel-plugin-react-compiler@latest

提示：启用此选项时，由于 React Compiler 依赖于 Babel，因此开发和构建期间的编译时间会更长。

缓存 API

revalidateTag

revalidateTag 具有新的函数签名。您可以将 cacheLife 配置文件作为第二个参数传递。

app/actions.ts
'use server'
 
import { revalidateTag } from 'next/cache'
 
export async function updateArticle(articleId: string) {
  // Mark article data as stale - article readers see stale data while it revalidates
  revalidateTag(`article-${articleId}`, 'max')
}

将 revalidateTag 用于更新延迟可接受的内容，例如博客文章、产品目录或文档。用户会收到旧内容，同时在后台加载新数据。

updateTag

updateTag 是一个新的仅限 服务器操作 的 API，它提供即时写入一致性语义，即用户进行更改后，UI 会立即显示更改，而不是旧数据。

它通过在同一请求中使数据过期并立即刷新数据来实现此目的。

app/actions.ts
'use server'
 
import { updateTag } from 'next/cache'
 
export async function updateUserProfile(userId: string, profile: Profile) {
  await db.users.update(userId, profile)
 
  // Expire cache and refresh immediately - user sees their changes right away
  updateTag(`user-${userId}`)
}

这确保了交互式功能能够立即反映更改。非常适合表单、用户设置以及任何用户期望立即看到其更新的工作流程。

在此处了解何时使用 updateTag 或 revalidateTag here。

refresh

refresh 允许您在服务器操作中刷新客户端路由器。

app/actions.ts
'use server'
 
import { refresh } from 'next/cache'
 
export async function markNotificationAsRead(notificationId: string) {
  // Update the notification in the database
  await db.notifications.markAsRead(notificationId)
 
  // Refresh the notification count displayed in the header
  refresh()
}

当您在执行操作后需要刷新客户端路由器时使用它。

cacheLife 和 cacheTag

cacheLife 和 cacheTag 现已稳定。不再需要 unstable_ 前缀。

无论您之前有别名导入，例如

import {
  unstable_cacheLife as cacheLife,
  unstable_cacheTag as cacheTag,
} from 'next/cache'

您可以将导入更新为

import { cacheLife, cacheTag } from 'next/cache'

增强的路由和导航

Next.js 16 对路由和导航系统进行了全面改造，使页面过渡更精简、更快。这优化了 Next.js 预取和缓存导航数据的方式

  • 布局去重：当预取多个具有共享布局的 URL 时，布局只会下载一次。
  • 增量预取：Next.js 只预取缓存中尚不存在的部分，而不是整个页面。

这些更改无需修改代码，旨在提高所有应用程序的性能。

但是，您可能会看到更多单独的预取请求，但总传输大小大大降低。我们相信这对于几乎所有应用程序来说都是正确的权衡。

如果增加的请求数量导致问题，请通过创建 issue 或 discussion 项目告知我们。

部分预渲染 (PPR)

Next.js 16 移除了实验性部分预渲染 (PPR) 标志和配置选项，包括路由级别段 experimental_ppr。

从 Next.js 16 开始，您可以使用 cacheComponents 配置选择 PPR。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  cacheComponents: true,
}
 
module.exports = nextConfig

Next.js 16 中的 PPR 工作方式与 Next.js 15 canary 版本不同。如果您当前正在使用 PPR，请停留在您正在使用的 Next.js 15 canary 版本中。我们将随后发布一份指南，指导您如何迁移到缓存组件。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // If you are using PPR today
  // stay in the current Next.js 15 canary
  experimental: {
    ppr: true,
  },
}
 
module.exports = nextConfig

middleware 到 proxy

middleware 文件名已被弃用，并已重命名为 proxy，以阐明网络边界和路由重点。

proxy 不支持 edge 运行时。proxy 运行时是 nodejs，并且无法配置。如果您想继续使用 edge 运行时，请继续使用 middleware。我们将在次要版本中提供进一步的 edge 运行时说明。

终端
# Rename your middleware file
mv middleware.ts proxy.ts
# or
mv middleware.js proxy.js

命名导出 middleware 也已弃用。将您的函数重命名为 proxy。

proxy.ts
export function proxy(request: Request) {}

我们建议将函数名称更改为 proxy，即使您使用默认导出。

包含 middleware 名称的配置标志也已重命名。例如，skipMiddlewareUrlNormalize 现在是 skipProxyUrlNormalize

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  skipProxyUrlNormalize: true,
}
 
export default nextConfig

版本 16 的 codemod 也能够更新这些标志。

next/image 更改

带查询字符串的本地图像（重大更改）

带有查询字符串的本地图像源现在需要 images.localPatterns.search 配置，以防止枚举攻击。

app/page.tsx
import Image from 'next/image'
 
export default function Page() {
  return <Image src="/assets/photo?v=1" alt="Photo" width="100" height="100" />
}

如果您需要将查询字符串与本地图像一起使用，请将模式添加到您的配置中

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/**',
        search: '?v=1',
      },
    ],
  },
}
 
export default nextConfig

minimumCacheTTL 默认值（重大更改）

images.minimumCacheTTL 的默认值已从 60 秒 更改为 4 小时（14400 秒）。这减少了没有 cache-control 标头的图像的重新验证成本。

对于一些 Next.js 用户来说，图像重新验证频繁发生，通常是因为上游源图像缺少 `cache-control` 标头。这导致每 60 秒重新验证一次，从而增加了 CPU 使用率和成本。

由于大多数图像不会频繁更改，因此如此短的间隔并不理想。将默认值设置为 4 小时可以提供更持久的缓存，同时仍允许图像在需要时每天更新几次。

如果您需要以前的行为，请将 minimumCacheTTL 更改为较低的值，例如改回 60 秒

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    minimumCacheTTL: 60,
  },
}
 
export default nextConfig

imageSizes 默认值（重大更改）

值 16 已从默认 images.imageSizes 数组中移除。

我们查看了请求分析，发现很少有项目使用 16 像素宽度的图像。删除此设置会减少 next/image 发送给浏览器的 srcset 属性的大小。

如果您需要支持 16 像素的图像

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}
 
export default nextConfig

我们认为 16 像素宽度的图像变得不那么常见，并不是因为开发者使用率低，而是因为 devicePixelRatio: 2 实际上会获取 32 像素的图像，以防止在 Retina 显示器中出现模糊。

qualities 默认值（重大更改）

images.qualities 的默认值已从允许所有质量更改为仅允许 [75]。

如果您需要支持多个质量级别

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    qualities: [50, 75, 100],
  },
}
 
export default nextConfig

如果指定的 `quality` prop 不包含在 `image.qualities` 数组中，则质量将被强制转换为 `images.qualities` 中最接近的值。例如，给定上述配置，`quality` prop 为 80，将被强制转换为 75。

本地 IP 限制（重大更改）

新的安全限制默认阻止本地 IP 优化。仅在专用网络中将 images.dangerouslyAllowLocalIP 设置为 true。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    dangerouslyAllowLocalIP: true, // Only for private networks
  },
}
 
export default nextConfig

最大重定向次数（重大更改）

images.maximumRedirects 的默认值已从无限制更改为最大 3 次重定向。

next.config.ts
import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  images: {
    maximumRedirects: 0, // Disable redirects
    // or
    maximumRedirects: 5, // Increase for edge cases
  },
}
 
export default nextConfig

next/legacy/image 组件（已弃用）

next/legacy/image 组件已弃用。请改用 next/image

// Before
import Image from 'next/legacy/image'
 
// After
import Image from 'next/image'

images.domains 配置（已弃用）

images.domains 配置已弃用。

next.config.js
// image.domains is deprecated
module.exports = {
  images: {
    domains: ['example.com'],
  },
}

请改用 images.remotePatterns 以提高安全性

next.config.js
// Use image.remotePatterns instead
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
      },
    ],
  },
}

并发 dev 和 build

next dev 和 next build 现在使用独立的输出目录，从而支持并发执行。next dev 命令输出到 .next/dev。这是新的默认行为，由 isolatedDevBuild 控制。

此外，锁定文件机制可防止在同一项目上出现多个 next dev 或 next build 实例。

由于开发服务器输出到 .next/dev，因此 Turbopack 跟踪命令应为

npx next internal trace .next/dev/trace-turbopack

并行路由 default.js 要求

所有 并行路由 插槽现在都要求显式 default.js 文件。没有它们，构建将失败。

要保持以前的行为，请创建一个调用 notFound() 或返回 null 的 default.js 文件。

app/@modal/default.tsx
import { notFound } from 'next/navigation'
 
export default function Default() {
  notFound()
}

或者返回 null

app/@modal/default.tsx
export default function Default() {
  return null
}

ESLint Flat Config

@next/eslint-plugin-next 现在默认使用 ESLint Flat Config 格式，与 ESLint v10 保持一致，后者将放弃对旧版配置的支持。

请务必查阅我们的 @next/eslint-plugin-next 插件的 API 参考。

如果您正在使用旧版 .eslintrc 格式，请考虑迁移到 flat config 格式。有关详细信息，请参阅 ESLint 迁移指南。

滚动行为覆盖

在 Next.js 以前的版本中，如果您通过 CSS 在 <html> 元素上全局设置了 scroll-behavior: smooth，Next.js 会在 SPA 路由转换期间覆盖它，如下所示

  1. 临时将 scroll-behavior 设置为 auto
  2. 执行导航（导致立即滚动到顶部）
  3. 恢复您原始的 scroll-behavior 值

这确保了页面导航始终感觉流畅和即时，即使您为页面内导航启用了平滑滚动。但是，这种操作可能很昂贵，尤其是在每次导航开始时。

在 Next.js 16 中，此行为已更改。默认情况下，Next.js 在导航期间不再覆盖您的 scroll-behavior 设置。

如果您希望 Next.js 执行此覆盖（以前的默认行为），请将 data-scroll-behavior="smooth" 属性添加到您的 <html> 元素中

app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en" data-scroll-behavior="smooth">
      <body>{children}</body>
    </html>
  )
}

性能改进

对 next dev 和 next start 命令进行了显著的性能优化，同时改进了终端输出，具有更清晰的格式、更好的错误消息和改进的性能指标。

Next.js 16 从 next build 输出中移除了 size 和 First Load JS 指标。我们发现在使用 React Server Components 的服务器驱动架构中，这些指标不准确。我们的 Turbopack 和 Webpack 实现都存在问题，并且在如何计算客户端组件负载方面存在分歧。

衡量实际路由性能最有效的方法是通过 Chrome Lighthouse 或 Vercel Analytics 等工具，这些工具侧重于核心 Web Vitals 和下载的资源大小。

next dev 配置加载

在以前的版本中，Next 配置文件在开发期间加载了两次

  • 当运行 next dev 命令时
  • 当 next dev 命令启动 Next.js 服务器时

这效率低下，因为 next dev 命令不需要配置文件来启动 Next.js 服务器。

此更改的结果是，在您的 Next.js 配置文件中，当运行 next dev 检查 process.argv 是否包含 'dev' 时，将返回 false。

提示：typegen 和 build 命令仍在 process.argv 中可见。

这对于在 next dev 上触发副作用的插件尤其重要。如果是这种情况，检查 NODE_ENV 是否设置为 development 可能就足够了。

next.config.js
import { startServer } from 'docs-lib/dev-server'
 
const isDev = process.env.NODE_ENV === 'development'
 
if (isDev) {
  startServer()
}
 
const nextConfig = {
  /* Your config options */
}
 
module.exports = nextConfig

或者，使用加载配置的 phase。

构建适配器 API (alpha)

继 构建适配器 RFC 之后，构建适配器 API 的第一个 alpha 版本现已可用。

构建适配器允许您创建自定义适配器，这些适配器可以连接到构建过程，使部署平台和自定义构建集成能够修改 Next.js 配置或处理构建输出。

next.config.js
const nextConfig = {
  experimental: {
    adapterPath: require.resolve('./my-adapter.js'),
  },
}
 
module.exports = nextConfig

在 RFC 讨论中分享您的反馈。

现代 Sass API

sass-loader 已升级到 v16，它支持 现代 Sass 语法和新功能。

移除

这些功能以前已被弃用，现在已移除

AMP 支持

AMP 的采用率显著下降，维护此功能增加了框架的复杂性。所有 AMP API 和配置均已移除

  • Next 配置文件中的 amp 配置
  • next/amp 钩子导入和使用 (useAmp)
// Removed
import { useAmp } from 'next/amp'
 
// Removed
export const config = { amp: true }
  • 从页面中移除 export const config = { amp: true }
next.config.js
const nextConfig = {
  // Removed
  amp: {
    canonicalBase: 'https://example.com',
  },
}
 
export default nextConfig

评估 AMP 是否仍然对您的用例有必要。现在，大多数性能优势可以通过 Next.js 的内置优化和现代网络标准来实现。

next lint 命令

next lint 命令已移除。请直接使用 Biome 或 ESLint。next build 不再运行 linting。

codemod 可用于自动化迁移

终端
npx @next/codemod@canary next-lint-to-eslint-cli .

Next.js 配置文件中的 eslint 选项也已移除。

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  // No longer supported
  // eslint: {},
}
 
export default nextConfig

运行时配置

serverRuntimeConfig 和 publicRuntimeConfig 已移除。请改用环境变量。

之前（Next.js 15）

next.config.js
module.exports = {
  serverRuntimeConfig: {
    dbUrl: process.env.DATABASE_URL,
  },
  publicRuntimeConfig: {
    apiUrl: '/api',
  },
}
pages/index.tsx
import getConfig from 'next/config'
 
export default function Page() {
  const { publicRuntimeConfig } = getConfig()
  return <p>API URL: {publicRuntimeConfig.apiUrl}</p>
}

之后（Next.js 16）

对于仅限服务器的值，直接在服务器组件中访问环境变量

app/page.tsx
async function fetchData() {
  const dbUrl = process.env.DATABASE_URL
  // Use for server-side operations only
  return await db.query(dbUrl, 'SELECT * FROM users')
}
 
export default async function Page() {
  const data = await fetchData()
  return <div>{/* render data */}</div>
}

提示：使用 taint API 来防止意外地将敏感的服务器值传递给客户端组件。

对于客户端可访问的值，请使用 NEXT_PUBLIC_ 前缀

.env.local
NEXT_PUBLIC_API_URL="/api"
app/components/client-component.tsx
'use client'
 
export default function ClientComponent() {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL
  return <p>API URL: {apiUrl}</p>
}

为确保在运行时读取环境变量（而不是在构建时打包），请在读取 process.env 之前使用 connection() 函数

app/page.tsx
import { connection } from 'next/server'
 
export default async function Page() {
  await connection()
  const config = process.env.RUNTIME_CONFIG
  return <p>{config}</p>
}

了解有关环境变量的更多信息。

devIndicators 选项

以下选项已从 devIndicators 中移除

  • appIsrStatus
  • buildActivity
  • buildActivityPosition

指示器本身仍然可用。

experimental.dynamicIO

experimental.dynamicIO 标志已重命名为 cacheComponents

更新您的 Next 配置文件，移除 dynamicIO 标志。

next.config.js
// Next.js 15 - experimental.dynamicIO is now removed
module.exports = {
  experimental: {
    dynamicIO: true,
  },
}

添加 cacheComponents 标志并设置为 true。

next.config.js
// Next.js 16 - use cacheComponents instead
module.exports = {
  cacheComponents: true,
}

unstable_rootParams

unstable_rootParams 函数已移除。我们正在开发一个替代 API，并将在即将发布的次要版本中发布。