NNext.js 中文网 GitHub

如何升级到版本 11

将你的 Next.js 应用从版本 10 升级到版本 11。

要升级到版本 11,请运行以下命令:

Terminal
npm i next@11 react@17 react-dom@17
Terminal
yarn add next@11 react@17 react-dom@17
Terminal
pnpm up next@11 react@17 react-dom@17
Terminal
bun add next@11 react@17 react-dom@17

小知识: 如果你使用 TypeScript,请确保同时将 @types/react 和 @types/react-dom 升级到对应的版本。

Webpack 5#

Webpack 5 现在是所有 Next.js 应用的默认版本。如果你没有自定义 webpack 配置,那么你的应用已经在使用 webpack 5。如果你确实有自定义的 webpack 配置,可以参阅 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 作为替代:

示例:

text
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 中已被弃用,因为不再需要它,此后一直是空操作(no-op)。在 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 中 unsized 已被移除。

移除 next/dynamic 上的 modules 属性#

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

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

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

移除 Head.rewind#

Head.rewind 自 Next.js 9.5 以来一直是空操作(no-op),在 Next.js 11 中它已被移除。你可以放心地移除对 Head.rewind 的使用。

默认排除 Moment.js 的语言区域(locale)#

Moment.js 默认包含许多语言区域(locale)的翻译。Next.js 现在默认自动排除这些语言区域,以优化使用 Moment.js 的应用的包体积。

要加载特定语言区域,请使用以下代码片段:

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:

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

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

  // 如果组件被卸载,请使用 `off` 方法
  // 取消订阅该事件:
  return () => {
    router.events.off('routeChangeStart', handleRouteChange)
  }
}, [router])

如果你的应用使用了 router.router.events(这是一个非公开的内部属性),请确保同样改用 router.events。

从 React 16 升级到 17#

React 17 引入了新的 JSX Transform,将 Next.js 长期以来的一项特性带给了更广泛的 React 生态:使用 JSX 时无需 import React from 'react'。使用 React 17 时,Next.js 会自动采用新的转换。此转换不会使 React 变量成为全局变量,而这是之前 Next.js 实现中一个意外的副作用。可以使用 codemod 来自动修复你意外使用了 React 却未导入它的情况。

大多数应用已经使用最新版本的 React,在 Next.js 11 中,最低 React 版本已更新为 17.0.2。

要升级,可以运行以下命令:

text
npm install react@latest react-dom@latest

或者使用 yarn:

text
yarn add react@latest react-dom@latest
Next.js 中文网