版本 11

要升级到版本 11，请运行以下命令：

终端

npm i next@11 react@17 react-dom@17

终端

yarn add next@11 react@17 react-dom@17

终端

pnpm up next@11 react@17 react-dom@17

终端

bun add next@11 react@17 react-dom@17

须知： 如果您使用 TypeScript，请确保同时升级 @types/react 和 @types/react-dom 至对应版本。

Webpack 5

Webpack 5 现已成为所有 Next.js 应用的默认配置。如果您没有自定义 webpack 配置，您的应用已在使用 webpack 5。若有自定义配置，可参考 Next.js webpack 5 文档获取升级指南。

默认清理 `distDir` 目录

构建输出目录（默认为 .next）现在默认会被清理，仅保留 Next.js 缓存文件。更多信息请参阅清理 distDir RFC。

若您的应用此前依赖此行为，可通过在 next.config.js 中添加 cleanDistDir: false 标志禁用新默认行为。

`next dev` 和 `next start` 支持 `PORT` 环境变量

Next.js 11 支持通过 PORT 环境变量设置应用运行端口。仍推荐使用 -p/--port 参数，但若您无法使用 -p，现可选择 PORT 作为替代方案：

示例：

PORT=4000 next start

`next.config.js` 支持图片导入配置

Next.js 11 支持通过 next/image 静态导入图片。此新特性依赖对图片导入的处理能力。若您此前使用了 next-images 或 next-optimized-images 包，可选择迁移至 next/image 内置支持，或禁用该功能：

next.config.js

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

移除 `pages/_app.js` 中的 `super.componentDidCatch()`

next/app 组件的 componentDidCatch 自 Next.js 9 起已被弃用（因其不再需要且实际无操作）。在 Next.js 11 中该方法已被移除。

若您的 pages/_app.js 包含自定义 componentDidCatch 方法，可移除 super.componentDidCatch 调用。

移除 `pages/_app.js` 中的 `Container`

该导出项自 Next.js 9 起已被弃用（因其不再需要且在开发时会显示警告）。在 Next.js 11 中已被移除。

若您的 pages/_app.js 从 next/app 导入 Container，可直接移除该导入。更多信息请参阅相关文档。

移除页面组件中的 `props.url` 用法

该属性自 Next.js 4 起已被弃用，并在开发时显示警告。随着 getStaticProps / getServerSideProps 的引入，这些方法已禁止使用 props.url。在 Next.js 11 中该属性被完全移除。

更多信息请参阅相关文档。

移除 `next/image` 的 `unsized` 属性

next/image 的 unsized 属性自 Next.js 10.0.1 起已被弃用。请改用 layout="fill"。在 Next.js 11 中该属性被移除。

移除 `next/dynamic` 的 `modules` 属性

next/dynamic 的 modules 和 render 选项自 Next.js 9.5 起已被弃用，目的是使 API 更接近 React.lazy。在 Next.js 11 中这些选项被移除。

该选项自 Next.js 8 后未在文档中提及，因此您的应用很可能未使用它。

若您的应用确实使用了 modules 和 render，请参考相关文档。

移除 `Head.rewind`

Head.rewind 自 Next.js 9.5 起实际无操作，在 Next.js 11 中被移除。您可以安全地移除相关代码。

默认排除 Moment.js 语言包

Moment.js 默认包含大量语言包。Next.js 现在默认自动排除这些语言包，以优化使用 Moment.js 应用的包体积。

要加载特定语言包，请使用以下代码片段：

import moment from 'moment'
import 'moment/locale/ja'

moment.locale('ja')

您可以通过在 next.config.js 中添加 excludeDefaultMomentLocales: false 禁用此新默认行为，但强烈建议不要禁用此优化，因为它能显著减小 Moment.js 体积。

更新 `router.events` 的用法

若您在渲染期间访问 router.events，请注意在 Next.js 11 中预渲染期间不再提供该属性。请确保在 useEffect 中访问：

useEffect(() => {
  const handleRouteChange = (url, { shallow }) => {
    console.log(
      `应用正在跳转至 ${url} ${
        shallow ? '使用' : '未使用'
      } 浅路由`
    )
  }

  router.events.on('routeChangeStart', handleRouteChange)

  // 组件卸载时取消事件订阅：
  return () => {
    router.events.off('routeChangeStart', handleRouteChange)
  }
}, [router])

若您的应用使用了内部属性 router.router.events（非公开 API），请改用 router.events。

React 17 引入了新的 JSX 转换，将 Next.js 长期支持的特性带入更广泛的 React 生态：使用 JSX 时无需 import React from 'react'。使用 React 17 时 Next.js 会自动启用新转换。此转换不会使 React 变量成为全局变量（这是之前 Next.js 实现的意外副作用）。我们提供了代码修改工具来自动修复未导入 React 就直接使用的情况。

大多数应用已使用最新版 React，Next.js 11 要求的最低 React 版本为 17.0.2。

升级可运行以下命令：

npm install react@latest react-dom@latest

或使用 yarn：

yarn add react@latest react-dom@latest