如何升级至版本 12

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

终端

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 至对应版本。

升级至 12.2

中间件 (Middleware) - 如果您在 12.2 之前使用了中间件，请参阅升级指南获取更多信息。

升级至 12.0

最低 Node.js 版本 - 最低 Node.js 版本要求已从 12.0.0 提升至 12.22.0，这是首个原生支持 ES 模块的 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@latest

SWC 替代 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，并回退至与 Next.js 11 相同的 Babel 使用方式。

当前需要自定义 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 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，或者更推荐的方式是，在 <Image> 组件外添加一个新的 <div className="wrapper"> 包裹层，并针对该层设置样式，例如 .container .wrapper。

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

更多信息请参阅文档。

HMR 连接现在使用 WebSocket

此前，Next.js 使用服务器发送事件 (server-sent events) 连接接收 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 已在 11 版本中将 webpack 5 作为默认编译工具。如 webpack 5 升级文档所述，Next.js 12 移除了对 webpack 4 的支持。

如果您的应用仍在使用 webpack 4 并通过标志禁用新特性，现在将看到指向 webpack 5 升级文档的错误提示。

`target` 选项已弃用

如果您的 next.config.js 中没有 target 选项，可以跳过本节。

target 选项已被弃用，转而支持内置的页面依赖追踪功能。

在 next build 过程中，Next.js 会自动追踪每个页面及其依赖项，以确定部署生产版本应用所需的所有文件。

如果您当前将 target 选项设置为 serverless，请阅读关于如何利用新输出 (output) 的文档。

On this page