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

next.config.js 設定選項

Next.js 可以透過專案根目錄中的 next.config.js 文件進行配置（例如位於 package.json 旁），並使用預設導出。

next.config.js
// @ts-check

/** @type {import('next').NextConfig} */
const nextConfig = {
  /* 在此處填入配置選項 */
}

module.exports = nextConfig

ECMAScript 模組

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

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

next.config.mjs
// @ts-check

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  /* 在此處填入配置選項 */
}

export default nextConfig

須知：目前不支援使用 .cjs、.cts 或 .mts 副檔名的 next.config 文件。

函數形式的配置

您也可以使用函數形式：

next.config.mjs
// @ts-check

export default (phase, { defaultConfig }) => {
  /**
   * @type {import('next').NextConfig}
   */
  const nextConfig = {
    /* 在此處填入配置選項 */
  }
  return nextConfig
}

非同步配置

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

next.config.js
// @ts-check

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

階段參數

phase 是載入配置時的當前上下文。您可以查看可用的階段。階段可以從 next/constants 導入：

next.config.js
// @ts-check

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

module.exports = (phase, { defaultConfig }) => {
  if (phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* 僅用於開發階段的配置選項 */
    }
  }

  return {
    /* 用於除開發階段外所有階段的配置選項 */
  }
}

TypeScript

如果您的專案使用 TypeScript，可以使用 next.config.ts 在配置中使用 TypeScript：

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  /* 在此處填入配置選項 */
}

export default nextConfig

註解行是您可以放置 next.config.js 允許的配置選項的位置，這些選項定義於此文件。

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

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

本頁面記錄了所有可用的配置選項：

單元測試 (實驗性功能)

從 Next.js 15.1 開始，next/experimental/testing/server 套件包含幫助測試 next.config.js 文件的工具。

unstable_getResponseFromNextConfig 函數會使用提供的請求資訊執行 next.config.js 中的 headers、redirects 和 rewrites 函數，並返回包含路由結果的 NextResponse。

unstable_getResponseFromNextConfig 的回應僅考慮 next.config.js 的欄位，不考慮中介軟體或文件系統路由，因此實際生產環境的結果可能與單元測試不同。

import {
  getRedirectUrl,
  unstable_getResponseFromNextConfig,
} from 'next/experimental/testing/server'

const response = await unstable_getResponseFromNextConfig({
  url: 'https://nextjs.org/test',
  nextConfig: {
    async redirects() {
      return [{ source: '/test', destination: '/test2', permanent: false }]
    },
  },
})
expect(response.status).toEqual(307)
expect(getRedirectUrl(response)).toEqual('https://nextjs.org/test2')

allowedDevOrigins

使用 `allowedDevOrigins` 設定可請求開發伺服器的額外來源。

assetPrefix

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

basePath

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

bundlePagesRouterDependencies

為 Pages Router 啟用自動依賴項打包功能

compress

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

crossOrigin

使用 `crossOrigin` 選項可在 `next/script` 和 `next/head` 生成的 `script` 標籤上添加跨來源標籤。

devIndicators

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

distDir

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

env

了解如何在建置時於 Next.js 應用程式中新增及存取環境變數。

eslint

Next.js 在構建時預設會回報 ESLint 錯誤與警告。此處將說明如何選擇退出此行為。

exportPathMap

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

generateBuildId

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

generateEtags

Next.js 預設會為每個頁面生成 etags。了解更多關於如何停用 etag 生成的資訊。

headers

為你的 Next.js 應用程式新增自訂 HTTP 標頭 (headers)

httpAgentOptions

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

images

關於 next/image 加載器的自定義配置

onDemandEntries

設定 Next.js 在開發環境中如何處置及保留記憶體中的頁面。

optimizePackageImports

關於 Next.js 設定選項 `optimizePackageImports` 的 API 參考文件

output

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

pageExtensions

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

poweredByHeader

Next.js 預設會加入 `x-powered-by` 標頭。在此了解如何選擇停用此功能。

productionBrowserSourceMaps

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

reactStrictMode

完整的 Next.js 執行環境現在已符合嚴格模式 (Strict Mode) 規範，了解如何啟用此功能

重新導向 (redirects)

為您的 Next.js 應用程式新增重新導向 (redirects) 功能。

rewrites

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

執行時期設定 (Runtime Config)

為您的 Next.js 應用程式新增客戶端與伺服器端的執行時期設定 (runtime configuration)。

serverExternalPackages

從 `bundlePagesRouterDependencies` 啟用的依賴打包中排除特定依賴項。

trailingSlash

設定 Next.js 頁面解析時是否包含尾部斜線。

transpilePackages

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

turbo

配置 Next.js 的 Turbopack 專屬選項

TypeScript

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

urlImports

配置 Next.js 以允許從外部 URL 導入模組。

useLightningcss

啟用 Lightning CSS 的實驗性支援。

webpack

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

webVitalsAttribution

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

ESLint

Next.js 在預設情況下會在構建過程中報告 ESLint 錯誤和警告。本文將介紹如何選擇退出此行為。

allowedDevOrigins

使用 `allowedDevOrigins` 設定可請求開發伺服器的額外來源。

On this page