版本 11

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

¥To upgrade to version 11, run the following command:

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 升级到相应的版本。

¥Good to know: If you are using TypeScript, ensure you also upgrade @types/react and @types/react-dom to their corresponding versions.

Webpack 5

Webpack 5 现在是所有 Next.js 应用的默认版本。如果你没有自定义 webpack 配置，则你的应用已经在使用 webpack 5。如果你确实有自定义 webpack 配置，可以参考 Next.js webpack 5 文档 获取升级指南。

¥Webpack 5 is now the default for all Next.js applications. If you did not have a custom webpack configuration, your application is already using webpack 5. If you do have a custom webpack configuration, you can refer to the Next.js webpack 5 documentation for upgrade guidance.

现在默认清洁 distDir

¥Cleaning the distDir is now a default

现在默认情况下会清除构建输出目录（默认为 .next），但 Next.js 缓存除外。你可以参考 清洁 distDir RFC 了解更多信息。

¥The build output directory (defaults to .next) is now cleared by default except for the Next.js caches. You can refer to the cleaning distDir RFC for more information.

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

¥If your application was relying on this behavior previously you can disable the new default behavior by adding the cleanDistDir: false flag in next.config.js.

PORT 现在支持 next dev 和 next start

¥PORT is now supported for next dev and next start

Next.js 11 支持 PORT 环境变量来设置应用运行的端口。仍然建议使用 -p/--port，但如果你被禁止以任何方式使用 -p，你现在可以使用 PORT 作为替代：

¥Next.js 11 supports the PORT environment variable to set the port the application runs on. Using -p/--port is still recommended but if you were prohibited from using -p in any way you can now use PORT as an alternative:

示例：

¥Example:

PORT=4000 next start

next.config.js 自定义导入图片

¥next.config.js customization to import images

Next.js 11 支持使用 next/image 导入静态图片。这项新功能依赖于处理图片导入的能力。如果你之前添加了 next-images 或 next-optimized-images 软件包，你可以使用 next/image 移动到新的内置支持或禁用该功能：

¥Next.js 11 supports static image imports with next/image. This new feature relies on being able to process image imports. If you previously added the next-images or next-optimized-images packages you can either move to the new built-in support using next/image or disable the feature:

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

从 pages/_app.js 中删除 super.componentDidCatch()

¥Remove super.componentDidCatch() from pages/_app.js

next/app 组件的 componentDidCatch 在 Next.js 9 中已被弃用，因为不再需要它并且从此成为无操作。在 Next.js 11 中，它被删除了。

¥The next/app component's componentDidCatch was deprecated in Next.js 9 as it's no longer needed and has since been a no-op. In Next.js 11, it was removed.

如果你的 pages/_app.js 有自定义 componentDidCatch 方法，你可以删除 super.componentDidCatch，因为不再需要它。

¥If your pages/_app.js has a custom componentDidCatch method you can remove super.componentDidCatch as it is no longer needed.

从 pages/_app.js 中删除 Container

¥Remove Container from pages/_app.js

此导出在 Next.js 9 中已被弃用，因为不再需要它，并且此后在开发过程中成为无操作并发出警告。在 Next.js 11 中它被删除了。

¥This export was deprecated in Next.js 9 as it's no longer needed and has since been a no-op with a warning during development. In Next.js 11 it was removed.

如果你的 pages/_app.js 从 next/app 导入 Container，你可以将 Container 删除，因为它已被删除。在 文档 中了解更多信息。

¥If your pages/_app.js imports Container from next/app you can remove Container as it was removed. Learn more in the documentation.

从页面组件中删除 props.url 使用

¥Remove props.url usage from page components

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

¥This property was deprecated in Next.js 4 and has since shown a warning during development. With the introduction of getStaticProps / getServerSideProps these methods already disallowed the usage of props.url. In Next.js 11, it was removed completely.

你可以在 文档 中了解更多信息。

¥You can learn more in the documentation.

删除 next/image 上的 unsized 属性

¥Remove unsized property on next/image

Next.js 10.0.1 中已弃用 next/image 上的 unsized 属性。你可以使用 layout="fill" 代替。在 Next.js 11 unsized 中被删除。

¥The unsized property on next/image was deprecated in Next.js 10.0.1. You can use layout="fill" instead. In Next.js 11 unsized was removed.

删除 next/dynamic 上的 modules 属性

¥Remove modules property on next/dynamic

Next.js 9.5 中已弃用 next/dynamic 的 modules 和 render 选项。这样做是为了使 next/dynamic API 更接近 React.lazy。在 Next.js 11 中，删除了 modules 和 render 选项。

¥The modules and render option for next/dynamic were deprecated in Next.js 9.5. This was done in order to make the next/dynamic API closer to React.lazy. In Next.js 11, the modules and render options were removed.

自 Next.js 8 以来，文档中未提及此选项，因此你的应用使用它的可能性较小。

¥This option hasn't been mentioned in the documentation since Next.js 8 so it's less likely that your application is using it.

如果你的应用确实使用了 modules 和 render，你可以参考 文档。

¥If your application does use modules and render you can refer to the documentation.

删除 Head.rewind

¥Remove Head.rewind

自 Next.js 9.5 以来，Head.rewind 一直是无操作，在 Next.js 11 中它被删除。你可以安全地删除对 Head.rewind 的使用。

¥Head.rewind has been a no-op since Next.js 9.5, in Next.js 11 it was removed. You can safely remove your usage of Head.rewind.

默认情况下排除 Moment.js 区域设置

¥Moment.js locales excluded by default

Moment.js 默认包含许多语言环境的翻译。Next.js 现在默认自动排除这些区域设置，以优化使用 Moment.js 的应用的包大小。

¥Moment.js includes translations for a lot of locales by default. Next.js now automatically excludes these locales by default to optimize bundle size for applications using Moment.js.

要加载特定区域设置，请使用以下代码片段：

¥To load a specific locale use this snippet:

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

moment.locale('ja')

如果你不想要新行为，你可以通过将 excludeDefaultMomentLocales: false 添加到 next.config.js 来选择退出此新默认设置，请注意，强烈建议不要禁用此新优化，因为它会显着减小 Moment.js 的大小。

¥You can opt-out of this new default by adding excludeDefaultMomentLocales: false to next.config.js if you do not want the new behavior, do note it's highly recommended to not disable this new optimization as it significantly reduces the size of Moment.js.

更新 router.events 的使用情况

¥Update usage of router.events

如果你在渲染期间访问 router.events，则在 Next.js 11 中，预渲染期间不再提供 router.events。确保你正在 useEffect 中访问 router.events：

¥In case you're accessing router.events during rendering, in Next.js 11 router.events is no longer provided during pre-rendering. Ensure you're accessing router.events in useEffect:

useEffect(() => {
  const handleRouteChange = (url, { shallow }) => {
    console.log(
      `App is changing to ${url} ${
        shallow ? 'with' : 'without'
      } shallow routing`
    )
  }

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

  // If the component is unmounted, unsubscribe
  // from the event with the `off` method:
  return () => {
    router.events.off('routeChangeStart', handleRouteChange)
  }
}, [router])

如果你的应用使用 router.router.events，这是一个非公开的内部属性，请确保也使用 router.events。

¥If your application uses router.router.events which was an internal property that was not public please make sure to use router.events as well.

React 16 至 17

¥React 16 to 17

React 17 引入了新的 JSX 变换，为更广泛的 React 生态系统带来了长期存在的 Next.js 功能：使用 JSX 时不必 import React from 'react'。使用 React 17 时，Next.js 将自动使用新的转换。此转换不会使 React 变量成为全局变量，这是先前 Next.js 实现的意外副作用。代码模式可用 自动修复你不小心使用 React 而不导入它的情况。

¥React 17 introduced a new JSX Transform that brings a long-time Next.js feature to the wider React ecosystem: Not having to import React from 'react' when using JSX. When using React 17 Next.js will automatically use the new transform. This transform does not make the React variable global, which was an unintended side-effect of the previous Next.js implementation. A codemod is available to automatically fix cases where you accidentally used React without importing it.

大多数应用已经使用最新版本的 React，Next.js 11 的最低 React 版本已更新至 17.0.2。

¥Most applications already use the latest version of React, with Next.js 11 the minimum React version has been updated to 17.0.2.

要升级，你可以运行以下命令：

¥To upgrade you can run the following command:

npm install react@latest react-dom@latest

或者使用 yarn：

¥Or using yarn:

yarn add react@latest react-dom@latest