跳到内容

Version 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。如果你有自定义 webpack 配置,你可以参考 Next.js webpack 5 文档 获取升级指南。

默认情况下现在清理 distDir

构建输出目录(默认为 .next)现在默认会被清除,除了 Next.js 缓存。你可以参考 清理 distDir RFC 获取更多信息。

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

PORT 现在支持 next devnext start

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

示例

PORT=4000 next start

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

Next.js 11 支持使用 next/image 静态导入图像。这项新功能依赖于处理图像导入的能力。如果你之前添加了 next-imagesnext-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.jsnext/app 导入了 Container,你可以删除 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/dynamicmodulesrender 选项在 Next.js 9.5 中已被弃用。这样做是为了使 next/dynamic API 更接近 React.lazy。在 Next.js 11 中,modulesrender 选项被移除。

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

如果你的应用确实使用了 modulesrender,你可以参考 文档

删除 Head.rewind

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

默认情况下排除 Moment.js locales

Moment.js 默认包含大量 locales 的翻译。Next.js 现在默认自动排除这些 locales,以优化使用 Moment.js 的应用的包大小。

要加载特定的 locale,请使用此代码片段

import moment from 'moment'
import 'moment/locale/ja'
 
moment.locale('ja')

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

更新 router.events 的用法

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

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

React 16 到 17

React 17 引入了一个新的 JSX 转换,它将 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。

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

npm install react@latest react-dom@latest

或者使用 yarn

yarn add react@latest react-dom@latest