Skip to main content

版本 12

要升级到版本 12，请运行以下命令：

¥To upgrade to version 12, run the following command:

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

很高兴知道：如果你使用的是 TypeScript，请确保还将 @types/react 和 @types/react-dom 升级到相应的版本。

¥Good to know: If you are using TypeScript, ensure you also upgrade @types/react and @types/react-dom to their corresponding versions.

升级到 12.2​

¥Upgrading to 12.2

中间件 - 如果你在 12.2 之前使用中间件，请参阅 升级指南 了解更多信息。

¥Middleware - If you were using Middleware prior to 12.2, please see the upgrade guide for more information.

升级到 12.0​

¥Upgrading to 12.0

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

¥Minimum Node.js Version - The minimum Node.js version has been bumped from 12.0.0 to 12.22.0 which is the first version of Node.js with native ES Modules support.

最低反应版本 - 所需的最低 React 版本是 17.0.2。要升级，你可以在终端中运行以下命令：

¥Minimum React Version - The minimum required React version is 17.0.2. To upgrade you can run the following command in the 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​

¥SWC replacing Babel

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

¥Next.js now uses the Rust-based compiler SWC to compile JavaScript/TypeScript. This new compiler is up to 17x faster than Babel when compiling individual files and up to 5x faster Fast Refresh.

Next.js 提供与具有 自定义 Babel 配置 的应用的完全向后兼容性。Next.js 默认处理的所有转换（例如 styled-jsx 和 getStaticProps / getStaticPaths / getServerSideProps 的 tree-shaking）都已移植到 Rust。

¥Next.js provides full backward compatibility with applications that have custom Babel configuration. All transformations that Next.js handles by default like styled-jsx and tree-shaking of getStaticProps / getStaticPaths / getServerSideProps have been ported to Rust.

当应用具有自定义 Babel 配置时，Next.js 将自动选择不使用 SWC 来编译 JavaScript/Typescript，并以与 Next.js 11 中相同的方式使用 Babel。

¥When an application has a custom Babel configuration, Next.js will automatically opt-out of using SWC for compiling JavaScript/Typescript and will fall back to using Babel in the same way that it was used in Next.js 11.

目前需要自定义 Babel 转换的许多与外部库的集成将在不久的将来移植到基于 Rust 的 SWC 转换。这些包括但不限于：

¥Many of the integrations with external libraries that currently require custom Babel transformations will be ported to Rust-based SWC transforms in the near future. These include but are not limited to:

  • 样式组件

    ¥Styled Components

  • Emotion

  • Relay

为了确定有助于你采用 SWC 的转换的优先顺序，请在 这个反馈线程 上提供你的 .babelrc。

¥In order to prioritize transforms that will help you adopt SWC, please provide your .babelrc on this feedback thread.

SWC 取代 Terser 进行缩小​

¥SWC replacing Terser for minification

你可以选择使用 SWC 替换 Terser，以便使用 next.config.js 中的标志将 JavaScript 压缩速度提高 7 倍：

¥You can opt-in to replacing Terser with SWC for minifying JavaScript up to 7x faster using a flag in next.config.js:

module.exports = {
  swcMinify: true,
}

使用 SWC 进行缩小是一个选择标志，以确保在成为 Next.js 12.1 中的默认设置之前，可以针对更真实的 Next.js 应用对其进行测试。如果你对缩小有任何反馈，请将其留在 这个反馈线程 上。

¥Minification using SWC is an opt-in flag to ensure it can be tested against more real-world Next.js applications before it becomes the default in Next.js 12.1. If you have feedback about minification, please leave it on this feedback thread.

styled-jsx CSS 解析的改进​

¥Improvements to styled-jsx CSS parsing

在基于 Rust 的编译器之上，我们基于用于 styled-jsx Babel 转换的解析器实现了一个新的 CSS 解析器。这个新的解析器改进了对 CSS 的处理，现在使用无效 CSS 时会出现错误，而这些错误以前会漏掉并导致意外行为。

¥On top of the Rust-based compiler we've implemented a new CSS parser based on the one used for the styled-jsx Babel transform. This new parser has improved handling of CSS and now errors when invalid CSS is used that would previously slip through and cause unexpected behavior.

由于此更改，无效的 CSS 将在开发和 next build 期间引发错误。此更改仅影响 styled-jsx 的使用。

¥Because of this change invalid CSS will throw an error during development and next build. This change only affects styled-jsx usage.

next/image 改变了封装元素​

¥next/image changed wrapping element

next/image 现在将 <img> 渲染在 <span> 内，而不是 <div>。

¥next/image now renders the <img> inside a <span> instead of <div>.

如果你的应用具有特定的 CSS 定位范围（例如 .container span），则升级到 Next.js 12 可能会错误地匹配 <Image> 组件内的封装元素。你可以通过将选择器限制为特定类（例如 .container span.item）并使用该类名（例如 <span className="item" />）更新相关组件来避免这种情况。

¥If your application has specific CSS targeting span such as .container span, upgrading to Next.js 12 might incorrectly match the wrapping element inside the <Image> component. You can avoid this by restricting the selector to a specific class such as .container span.item and updating the relevant component with that className, such as <span className="item" />.

如果你的应用具有针对 next/image <div> 标记的特定 CSS（例如 .container div），则它可能不再匹配。你可以更新选择器 .container span，或者最好添加一个新的 <div className="wrapper"> 来封装 <Image> 组件和目标，例如 .container .wrapper。

¥If your application has specific CSS targeting the next/image <div> tag, for example .container div, it may not match anymore. You can update the selector .container span, or preferably, add a new <div className="wrapper"> wrapping the <Image> component and target that instead such as .container .wrapper.

className 属性保持不变，仍会传递给底层 <img> 元素。

¥The className prop is unchanged and will still be passed to the underlying <img> element.

请参阅 documentation 了解更多信息。

¥See the documentation for more info.

HMR 连接现在使用 WebSocket​

¥HMR connection now uses a WebSocket

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

¥Previously, Next.js used a server-sent events connection to receive HMR events. Next.js 12 now uses a WebSocket connection.

在某些情况下，当将请求代理到 Next.js 开发服务器时，你需要确保正确处理升级请求。例如，在 nginx 中，你需要添加以下配置：

¥In some cases when proxying requests to the Next.js dev server, you will need to ensure the upgrade request is handled correctly. For example, in nginx you would need to add the following configuration:

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 套接字。检查端口、主机名和服务器名称。

¥If you are using Apache (2.x), you can add the following configuration to enable web sockets to the server. Review the port, host name and server names.

<VirtualHost *:443>
 # ServerName yourwebsite.local
 ServerName "${WEBSITE_SERVER_NAME}"
 ProxyPass / http://localhost:3000/
 ProxyPassReverse / http://localhost:3000/
 # Next.js 12 uses 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 来确保请求正确传递，例如：

¥For custom servers, such as express, you may need to use app.all to ensure the request is passed correctly, for example:

app.all('/_next/webpack-hmr', (req, res) => {
  nextjsRequestHandler(req, res)
})

Webpack 4 支持已被删除​

¥Webpack 4 support has been removed

如果你已经在使用 webpack 5，则可以跳过本节。

¥If you are already using webpack 5 you can skip this section.

Next.js 在 Next.js 11 中默认采用 webpack 5 进行编译。正如 webpack 5 升级文档 中所述，Next.js 12 删除了对 webpack 4 的支持。

¥Next.js has adopted webpack 5 as the default for compilation in Next.js 11. As communicated in the webpack 5 upgrading documentation Next.js 12 removes support for webpack 4.

如果你的应用仍在使用带有 opt-out 标志的 webpack 4，你现在将看到链接到 webpack 5 升级文档 的错误。

¥If your application is still using webpack 4 using the opt-out flag, you will now see an error linking to the webpack 5 upgrading documentation.

target 选项已弃用​

¥target option deprecated

如果你在 next.config.js 中没有 target，则可以跳过本节。

¥If you do not have target in next.config.js you can skip this section.

目标选项已被弃用，取而代之的是用于跟踪运行页面所需的依赖的内置支持。

¥The target option has been deprecated in favor of built-in support for tracing what dependencies are needed to run a page.

在 next build 期间，Next.js 将自动跟踪每个页面及其依赖，以确定部署应用的生产版本所需的所有文件。

¥During next build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a production version of your application.

如果你当前使用的 target 选项设置为 serverless，请阅读 有关如何利用新输出的文档。

¥If you are currently using the target option set to serverless, please read the documentation on how to leverage the new output.