如何升级到版本 11
将你的 Next.js 应用从版本 10 升级到版本 11。
要升级到版本 11,请运行以下命令:
npm i next@11 react@17 react-dom@17yarn add next@11 react@17 react-dom@17pnpm up next@11 react@17 react-dom@17bun 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 作为替代:
示例:
PORT=4000 next start通过 next.config.js 自定义以导入图片#
Next.js 11 支持通过 next/image 静态导入图片。这项新功能依赖于处理图片导入的能力。如果你之前添加过 next-images 或 next-optimized-images 包,可以改用 next/image 的新内置支持,或禁用该功能:
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 的应用的包体积。
要加载特定语言区域,请使用以下代码片段:
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(
`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。
要升级,可以运行以下命令:
npm install react@latest react-dom@latest或者使用 yarn:
yarn add react@latest react-dom@latest