logoNext.js 繁體中文
文件部落格學習
介紹/API 參考文檔/next.config.js 設定選項

next.config.js 設定選項

Next.js 可以透過專案根目錄中的 next.config.js 檔案進行設定（例如位於 package.json 旁）。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在此處填入設定選項 */
}

module.exports = nextConfig

next.config.js 是一個標準的 Node.js 模組，而非 JSON 檔案。它會被 Next.js 伺服器和建構階段使用，但不會包含在瀏覽器建構中。

如果您需要使用 ECMAScript 模組，可以使用 next.config.mjs：

next.config.mjs
/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* 在此處填入設定選項 */
}

export default nextConfig

您也可以使用函式形式：

next.config.mjs
module.exports = (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* 在此處填入設定選項 */
  }
  return nextConfig
}

自 Next.js 12.1.0 起，您可以使用非同步函式：

next.config.js
module.exports = async (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* 在此處填入設定選項 */
  }
  return nextConfig
}

phase 是載入設定時的當前上下文。您可以查看可用的階段常數。這些階段常數可從 next/constants 匯入：

const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 僅開發環境的設定選項 */
    }
  }

  return {
    /* 除開發環境外所有階段的設定選項 */
  }
}

註解行是您可以放置 next.config.js 允許的設定選項的位置，這些選項定義於此檔案中。

然而，沒有任何設定是必須的，您也不需要理解每個設定的作用。相反地，您可以在本節中搜尋需要啟用或修改的功能，它們會告訴您該怎麼做。

請避免使用目標 Node.js 版本不支援的新 JavaScript 功能。next.config.js 不會被 Webpack、Babel 或 TypeScript 解析。

本文件列出了所有可用的設定選項：

appDir

啟用 App Router 以使用佈局 (layouts)、串流 (streaming) 等功能。

assetPrefix

了解如何使用 assetPrefix 配置選項來設定你的 CDN。

basePath

使用 `basePath` 將 Next.js 應用程式部署在網域的子路徑下。

compress

Next.js 提供 gzip 壓縮功能來壓縮渲染內容和靜態檔案，此功能僅適用於伺服器目標。了解更多相關資訊。

devIndicators

經過優化的頁面會包含一個指示器，讓您知道它是否正在進行靜態優化。您可以在這裡選擇關閉此功能。

distDir

設定自訂建置目錄以取代預設的 .next 目錄。

env

學習如何在建置時於 Next.js 應用程式中加入與存取環境變數。

eslint

Next.js 在構建時預設會報告 ESLint 錯誤和警告。本文將介紹如何停用此行為。

exportPathMap

自訂在使用 `next export` 時會被匯出為 HTML 檔案的頁面。

generateBuildId

設定建置 ID，該 ID 用於識別當前提供服務的應用程式版本。

generateEtags

Next.js 預設會為每個頁面生成 etags。在此了解如何停用 etag 生成功能。

headers

為您的 Next.js 應用程式添加自訂 HTTP 標頭。

httpAgentOptions

Next.js 預設會自動使用 HTTP Keep-Alive。了解更多關於如何停用 HTTP Keep-Alive 的資訊。

圖片

next/image 載入器的自訂設定

incrementalCacheHandlerPath

配置 Next.js 用於儲存和重新驗證資料的快取機制。

mdxRs

在 App Router 中使用新的 Rust 編譯器來編譯 MDX 檔案。

onDemandEntries

配置 Next.js 在開發環境中如何釋放與保留記憶體中的頁面。

optimizePackageImports

關於 Next.js 配置選項 `optimizePackageImports` 的 API 參考文件

output

Next.js 會自動追蹤每個頁面所需的檔案，以便輕鬆部署應用程式。在此了解其運作原理。

pageExtensions

擴展 Next.js 在解析 Pages Router 時使用的預設頁面副檔名。

poweredByHeader

了解如何停用 Next.js 預設添加的 `x-powered-by` 標頭。

productionBrowserSourceMaps

啟用在生產環境建置時生成瀏覽器原始碼映射 (source maps) 的功能。

reactStrictMode

Next.js 完整運行時現在已符合嚴格模式規範，了解如何啟用此功能

重新導向 (redirects)

在您的 Next.js 應用程式中新增重新導向功能。

rewrites

在您的 Next.js 應用程式中新增 rewrites 功能。

serverComponentsExternalPackages

選擇特定依賴項不參與伺服器元件 (Server Components) 打包，直接使用原生 Node.js 的 `require`。

trailingSlash

設定 Next.js 頁面是否解析結尾斜線。

transpilePackages

自動轉譯並打包來自本地套件（如 monorepos）或外部依賴（`node_modules`）的相依套件。

turbo

設定 Next.js 的 Turbopack 專屬選項

typedRoutes

啟用靜態類型連結的實驗性支援。

TypeScript

Next.js 預設會報告 TypeScript 錯誤。在此了解如何停用此行為。

urlImports

設定 Next.js 允許從外部 URL 匯入模組 (實驗性功能)。

webpack

了解如何自訂 Next.js 使用的 webpack 設定

webVitalsAttribution

了解如何使用 webVitalsAttribution 選項來定位 Web Vitals 問題的來源。

useSelectedLayoutSegments

關於 `useSelectedLayoutSegments` 鉤子的 API 參考文件。

appDir

啟用 App Router 以使用佈局 (layouts)、串流 (streaming) 等功能。