Sponsor
ntab.devntab.dev 提升效率的新标签页组件
点击查看
Menu

版本 12

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

Terminal
npm i next@12 react@17 react-dom@17 eslint-config-next@12
Terminal
yarn add next@12 react@17 react-dom@17 eslint-config-next@12
Terminal
pnpm up next@12 react@17 react-dom@17 eslint-config-next@12
Terminal
bun add next@12 react@17 react-dom@17 eslint-config-next@12

值得注意的是: 如果你正在使用 TypeScript,请确保同时将 @types/react@types/react-dom 升级到对应的版本。

升级到 12.2

中间件 - 如果你在 12.2 之前使用了中间件,请查看升级指南以获取更多信息。

升级到 12.0

最低 Node.js 版本 - 最低 Node.js 版本已从 12.0.0 提升到 12.22.0,这是第一个支持原生 ES 模块的 Node.js 版本。

最低 React 版本 - 最低所需 React 版本是 17.0.2。要升级,你可以在终端中运行以下命令:

Terminal
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@latest

SWC 替换 Babel

Next.js 现在使用基于 Rust 的编译器 SWC 来编译 JavaScript/TypeScript。这个新编译器在编译单个文件时比 Babel 快 17 倍,快速刷新速度提高 5 倍。

Next.js 为具有自定义 Babel 配置的应用程序提供了完全的向后兼容性。Next.js 默认处理的所有转换,如 styled-jsx 和 getStaticProps / getStaticPaths / getServerSideProps 的树摇,都已移植到 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 倍:

next.config.js
module.exports = {
  swcMinify: true,
}

使用 SWC 进行压缩是一个可选标志,以确保它可以在更多真实世界的 Next.js 应用程序中进行测试,然后在 Next.js 12.1 中成为默认选项。如果你对压缩有任何反馈,请在这个反馈帖子中留言。

改进 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,并更新相关组件的类名,如 <span className="item" />

如果你的应用程序有针对 next/image<div> 标签的特定 CSS,例如 .container div,它可能不再匹配。你可以将选择器更新为 .container span,或者最好是在 <Image> 组件周围添加一个新的 <div className="wrapper">,并针对它,例如 .container .wrapper

className 属性保持不变,仍将传递给底层的 <img> 元素。

请查看文档了解更多信息。

HMR 连接现在使用 WebSocket

之前,Next.js 使用服务器发送事件连接来接收 HMR 事件。Next.js 12 现在使用 WebSocket 连接。

在代理请求到 Next.js 开发服务器的某些情况下,你需要确保正确处理升级请求。例如,在 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),可以添加以下配置以在服务器上启用 WebSocket。请检查端口、主机名和服务器名。

<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)
})

移除 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 将自动跟踪每个页面及其依赖项,以确定部署应用程序生产版本所需的所有文件。

如果你目前使用设置为 serverlesstarget 选项,请阅读关于如何利用新输出的文档