如何升級至第 11 版

要升級至第 11 版，請執行以下指令：

npm i next@11 react@17 react-dom@17

yarn add next@11 react@17 react-dom@17

pnpm up next@11 react@17 react-dom@17

bun add next@11 react@17 react-dom@17

小提醒： 如果您使用 TypeScript，請確保同時升級 @types/react 和 @types/react-dom 至對應版本。

Webpack 5

Webpack 5 現在是所有 Next.js 應用程式的預設設定。如果您沒有自訂 webpack 配置，您的應用程式已經在使用 webpack 5。如果您有自訂 webpack 配置，可以參考 Next.js webpack 5 文件 獲取升級指引。

現在預設會清理 distDir

建置輸出目錄 (預設為 .next) 現在預設會被清理，但 Next.js 快取除外。更多資訊請參考 清理 distDir RFC。

如果您的應用程式之前依賴此行為，可以透過在 next.config.js 中加入 cleanDistDir: false 標記來停用新的預設行為。

next dev 和 next start 現在支援 PORT 環境變數

Next.js 11 支援使用 PORT 環境變數來設定應用程式運行的埠號。雖然仍建議使用 -p/--port，但如果您因故無法使用 -p，現在可以使用 PORT 作為替代方案：

範例：

PORT=4000 next start

next.config.js 自訂以匯入圖片

Next.js 11 支援透過 next/image 靜態匯入圖片。此新功能依賴於能夠處理圖片匯入。如果您之前安裝了 next-images 或 next-optimized-images 套件，可以選擇改用 next/image 內建支援，或停用此功能：

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

從 pages/_app.js 移除 super.componentDidCatch()

next/app 元件的 componentDidCatch 在 Next.js 9 已被棄用，因為不再需要且之後已無實際作用。在 Next.js 11 中，它已被移除。

如果您的 pages/_app.js 有自訂的 componentDidCatch 方法，可以移除 super.componentDidCatch，因為它已不再需要。

從 pages/_app.js 移除 Container

此匯出在 Next.js 9 已被棄用，因為不再需要且之後在開發時僅會顯示警告而無實際作用。在 Next.js 11 中，它已被移除。

如果您的 pages/_app.js 從 next/app 匯入 Container，可以移除 Container，因為它已被移除。更多資訊請參考 文件。

移除頁面元件中的 props.url 使用

此屬性在 Next.js 4 已被棄用，之後在開發時會顯示警告。隨著 getStaticProps / getServerSideProps 的引入，這些方法已禁止使用 props.url。在 Next.js 11 中，它已被完全移除。

更多資訊請參考 文件。

移除 next/image 的 unsized 屬性

next/image 的 unsized 屬性在 Next.js 10.0.1 已被棄用。您可以使用 layout="fill" 替代。在 Next.js 11 中，unsized 已被移除。

移除 next/dynamic 的 modules 屬性

next/dynamic 的 modules 和 render 選項在 Next.js 9.5 已被棄用。這是為了讓 next/dynamic API 更接近 React.lazy。在 Next.js 11 中，modules 和 render 選項已被移除。

此選項自 Next.js 8 後就未在文件中提及，因此您的應用程式不太可能使用它。

如果您的應用程式確實使用 modules 和 render，請參考 文件。

移除 Head.rewind

Head.rewind 自 Next.js 9.5 起已無實際作用，在 Next.js 11 中已被移除。您可以安全地移除對 Head.rewind 的使用。

預設排除 Moment.js 地區設定

Moment.js 預設包含許多地區設定的翻譯。Next.js 現在預設會自動排除這些地區設定，以優化使用 Moment.js 的應用程式的套件大小。

要載入特定地區設定，請使用以下程式碼片段：

import moment from 'moment'
import 'moment/locale/ja'

moment.locale('ja')

如果您不希望使用此新預設行為，可以在 next.config.js 中加入 excludeDefaultMomentLocales: false 來停用。但請注意，強烈建議不要停用此優化，因為它能顯著減少 Moment.js 的大小。

更新 router.events 的使用方式

如果您在渲染期間存取 router.events，請注意在 Next.js 11 中，router.events 在預渲染期間不再提供。請確保您在 useEffect 中存取 router.events：

useEffect(() => {
  const handleRouteChange = (url, { shallow }) => {
    console.log(
      `App is changing to ${url} ${
        shallow ? 'with' : 'without'
      } shallow routing`
    )
  }

  router.events.on('routeChangeStart', handleRouteChange)

  // 如果元件卸載，使用 'off' 方法取消訂閱事件：
  return () => {
    router.events.off('routeChangeStart', handleRouteChange)
  }
}, [router])

如果您的應用程式使用 router.router.events (這是一個未公開的內部屬性)，請確保改用 router.events。

從 React 16 升級至 17

React 17 引入了新的 JSX 轉換，將 Next.js 長期以來的功能帶入更廣泛的 React 生態系統：使用 JSX 時不再需要 import React from 'react'。當使用 React 17 時，Next.js 會自動使用新的轉換。此轉換不會使 React 變數成為全域變數，這是之前 Next.js 實現的意外副作用。我們提供了一個 codemod 工具 來自動修復您意外使用未匯入的 React 的情況。

大多數應用程式已經使用最新版本的 React，隨著 Next.js 11 的發布，最低要求的 React 版本已更新至 17.0.2。

要升級，您可以執行以下指令：

npm install react@latest react-dom@latest

或使用 yarn：

yarn add react@latest react-dom@latest