如何升级到版本 12
将你的 Next.js 应用从版本 11 升级到版本 12。
要升级到版本 12,请运行以下命令:
npm i next@12 react@17 react-dom@17 eslint-config-next@12yarn add next@12 react@17 react-dom@17 eslint-config-next@12pnpm up next@12 react@17 react-dom@17 eslint-config-next@12bun add next@12 react@17 react-dom@17 eslint-config-next@12小知识: 如果你正在使用 TypeScript,请确保同时将
@types/react和@types/react-dom升级到相应版本。
升级到 12.2#
Middleware - 如果你在 12.2 之前使用 Middleware,请参阅升级指南了解更多信息。
升级到 12.0#
最低 Node.js 版本 - 最低 Node.js 版本已从 12.0.0 提升到 12.22.0,这是首个原生支持 ES Modules 的 Node.js 版本。
最低 React 版本 - 所需的最低 React 版本为 17.0.2。要升级,你可以在终端中运行以下命令:
npm install react@latest react-dom@latest
yarn add react@latest react-dom@latest
pnpm update react@latest react-dom@latest
bun add react@latest react-dom@latestSWC 取代 Babel#
Next.js 现在使用基于 Rust 的编译器 SWC 来编译 JavaScript/TypeScript。在编译单个文件时,这个新编译器比 Babel 快多达 17 倍,Fast Refresh 也快多达 5 倍。
Next.js 对具有自定义 Babel 配置的应用提供完全的向后兼容。Next.js 默认处理的所有转换,如 styled-jsx 以及 getStaticProps / getStaticPaths / getServerSideProps 的 tree-shaking,都已移植到 Rust。
当应用具有自定义 Babel 配置时,Next.js 将自动选择不使用 SWC 来编译 JavaScript/TypeScript,并回退到使用 Babel,方式与在 Next.js 11 中相同。
目前需要自定义 Babel 转换的许多外部库集成将在不久后移植到基于 Rust 的 SWC 转换。这些包括但不限于:
- Styled Components
- Emotion
- Relay
为了优先处理有助于你采用 SWC 的转换,请在此反馈帖中提供你的 .babelrc。
SWC 取代 Terser 进行代码压缩#
你可以通过 next.config.js 中的标志选择使用 SWC 替代 Terser 来压缩 JavaScript,速度最多可提升 7 倍:
module.exports = {
swcMinify: true,
}使用 SWC 进行压缩是一个选择性启用的标志,以确保在它成为 Next.js 12.1 的默认设置之前,能在更多真实世界的 Next.js 应用中得到测试。如果你对压缩有反馈,请在此反馈帖中留言。
styled-jsx CSS 解析的改进#
在基于 Rust 的编译器之上,我们实现了一个新的 CSS 解析器,它基于 styled-jsx Babel 转换所使用的解析器。这个新解析器改进了对 CSS 的处理,现在当使用无效 CSS 时会报错,而之前这类问题会被忽略并导致意外行为。
由于这一变化,无效 CSS 将在开发过程和 next build 期间抛出错误。此更改仅影响 styled-jsx 的使用。
next/image 更改了包裹元素#
next/image 现在将 <img> 渲染在 <span> 中,而不是 <div> 中。
如果你的应用中有专门针对 span 的 CSS(例如 .container span),升级到 Next.js 12 可能会错误地匹配 <Image> 组件内的包裹元素。你可以通过将选择器限制为特定的类(例如 .container span.item),并使用该 className 更新相关组件(例如 <span className="item" />)来避免这种情况。
如果你的应用中有专门针对 next/image 的 <div> 标签的 CSS(例如 .container div),它可能不再匹配。你可以更新选择器为 .container span,或者更好的做法是,添加一个新的 <div className="wrapper"> 来包裹 <Image> 组件,并改为针对它,例如 .container .wrapper。
className 属性保持不变,仍会传递给底层的 <img> 元素。
更多信息请参阅文档。
HMR 连接现在使用 WebSocket#
以前,Next.js 使用 server-sent events 连接来接收 HMR 事件。Next.js 12 现在使用 WebSocket 连接。
在某些情况下,当将请求代理到 Next.js 开发服务器时,你需要确保 upgrade 请求被正确处理。例如,在 nginx 中你需要添加以下配置:
location /_next/webpack-hmr {
proxy_pass http://localhost:3000/_next/webpack-hmr;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}如果你使用的是 Apache (2.x),可以添加以下配置来为服务器启用 web sockets。请检查端口、主机名和服务器名称。
<VirtualHost *:443>
# ServerName yourwebsite.local
ServerName "${WEBSITE_SERVER_NAME}"
ProxyPass / http://localhost:3000/
ProxyPassReverse / http://localhost:3000/
# Next.js 12 使用 websocket
<Location /_next/webpack-hmr>
RewriteEngine On
RewriteCond %{QUERY_STRING} transport=websocket [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule /(.*) ws://localhost:3000/_next/webpack-hmr/$1 [P,L]
ProxyPass ws://localhost:3000/_next/webpack-hmr retry=0 timeout=30
ProxyPassReverse ws://localhost:3000/_next/webpack-hmr
</Location>
</VirtualHost>对于自定义服务器(例如 express),你可能需要使用 app.all 来确保请求被正确传递,例如:
app.all('/_next/webpack-hmr', (req, res) => {
nextjsRequestHandler(req, res)
})注意: 在 Next.js 16 中,HMR WebSocket 路径已从
/_next/webpack-hmr重命名为/_next/hmr。
已移除对 Webpack 4 的支持#
如果你已经在使用 webpack 5,可以跳过本节。
Next.js 在 Next.js 11 中已采用 webpack 5 作为默认编译工具。正如webpack 5 升级文档中所述,Next.js 12 移除了对 webpack 4 的支持。
如果你的应用仍使用该选择退出标志使用 webpack 4,现在你将看到一个错误,其中链接指向 webpack 5 升级文档。
target 选项已弃用#
如果你的 next.config.js 中没有 target,可以跳过本节。
target 选项已弃用,取而代之的是对追踪运行页面所需依赖项的内置支持。
在 next build 期间,Next.js 将自动追踪每个页面及其依赖项,以确定部署应用生产版本所需的所有文件。
如果你目前使用设置为 serverless 的 target 选项,请阅读关于如何利用新输出的文档。