第 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