版本 11

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

终端

npm install next@11

yarn add next@11

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 后文档中已不再提及此选项，因此您的应用很可能未使用它。

若确实使用，请参考相关文档。

移除 `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，请改用公开的 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