如何升級至第 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 版

中介軟體 (Middleware) - 如果您在 12.2 之前使用中介軟體，請參閱升級指南以獲取更多資訊。

升級至 12.0 版

最低 Node.js 版本要求 - 最低 Node.js 版本已從 12.0.0 提升至 12.22.0，這是首個支援原生 ES 模組 (ES Modules) 的 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 倍，在快速重新整理 (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 的編譯器外，我們還實現了一個基於 styled-jsx Babel 轉換使用的新 CSS 解析器。這個新解析器改進了對 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 開發伺服器時，您需要確保升級請求被正確處理。例如，在 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 會自動追蹤每個頁面及其依賴項，以確定部署應用程式生產版本所需的所有檔案。

如果您目前將 target 選項設為 serverless，請閱讀關於如何利用新輸出的文件。

On this page