如何升级至版本 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 起已弃用。此举旨在使 next/dynamic API 更接近 React.lazy。Next.js 11 中这些选项已被移除。

自 Next.js 8 起文档中已不再提及此选项，因此您的应用大概率未使用它。

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

移除 `Head.rewind`

自 Next.js 9.5 起 Head.rewind 实际无操作，Next.js 11 中该方法已被移除。您可安全移除对 Head.rewind 的调用。

默认排除 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 中预渲染期间不再提供 router.events。请确保在 useEffect 中访问 router.events：

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

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

  // 组件卸载时通过 `off` 方法取消订阅：
  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