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` 來設定可向開發伺服器發送請求的額外來源。

appDir

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

assetPrefix

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

authInterrupts

了解如何啟用實驗性的 `authInterrupts` 配置選項來使用 `forbidden` 和 `unauthorized`。

basePath

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

cacheLife

了解如何在 Next.js 中設定 cacheLife 配置。

compress

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

crossOrigin

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

cssChunking

使用 `cssChunking` 選項來控制 Next.js 應用程式中的 CSS 檔案分塊方式。

devIndicators

開發期間顯示當前路由相關資訊的螢幕指示器設定選項。

distDir

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

dynamicIO

了解如何在 Next.js 中啟用 dynamicIO 實驗性功能

env

學習如何在建置階段為您的 Next.js 應用程式新增及存取環境變數 (environment variables)。

eslint

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

expireTime

為啟用 ISR 的頁面自訂 stale-while-revalidate 過期時間。

exportPathMap

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

generateBuildId

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

generateEtags

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

headers

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

htmlLimitedBots

指定應接收封鎖元資料的使用者代理清單。

httpAgentOptions

Next.js 預設會自動使用 HTTP Keep-Alive。進一步了解如何在此停用 HTTP Keep-Alive。

圖片

關於 next/image 載入器的自訂配置

cacheHandler

設定 Next.js 快取用於儲存和重新驗證資料，可搭配任何外部服務如 Redis、Memcached 或其他服務使用。

inlineCss

啟用行內 CSS 支援功能。

日誌記錄

設定在開發模式下執行 Next.js 時，如何將資料擷取記錄到控制台。

mdxRs

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

onDemandEntries

設定 Next.js 在開發環境中如何釋放和保留記憶體中的頁面。

optimizePackageImports

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

output

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

pageExtensions

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

poweredByHeader

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

部分預渲染 (PPR)

了解如何在 Next.js 中啟用部分預渲染 (Partial Prerendering) 功能。

productionBrowserSourceMaps

在生产环境构建时启用浏览器原始碼映射 (source map) 生成功能。

reactCompiler

啟用 React 編譯器 (React Compiler) 來自動優化元件渲染。

reactMaxHeadersLength

關於 React 發出並添加到回應中的標頭最大長度設定。

reactStrictMode

Next.js 完整運行時環境現已相容嚴格模式，了解如何啟用此功能

重新導向 (redirects)

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

rewrites

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

sassOptions

配置 Sass 編譯器選項。

serverActions

在您的 Next.js 應用程式中設定 伺服器動作 (Server Actions) 行為。

serverComponentsHmrCache

設定伺服器元件 (Server Components) 中的 fetch 回應是否在 HMR 重新整理請求間進行快取。

serverExternalPackages

將特定依賴項從伺服器元件 (Server Components) 打包中排除，並使用原生 Node.js 的 `require`。

staleTimes

了解如何覆寫客戶端路由快取 (Client Router Cache) 的失效時間。

staticGeneration*

了解如何在你的 Next.js 應用程式中配置靜態生成 (Static Generation) 設定。

taint

啟用物件與值的汙染 (taint) 功能。

trailingSlash

配置 Next.js 頁面是否解析結尾斜線。

transpilePackages

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

turbopack

設定 Next.js 的 Turbopack 專屬選項

typedRoutes

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

TypeScript

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

urlImports

設定 Next.js 允許從外部 URL 導入模組。

useCache

了解如何在 Next.js 中啟用 useCache 標誌

useLightningcss

啟用 Lightning CSS 的實驗性支援。

viewTransition

在 App Router 中啟用 React 的 ViewTransition API

webpack

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

webVitalsAttribution

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

ESLint

了解如何使用和配置 ESLint 插件，以捕捉 Next.js 應用程式中的常見問題和錯誤。

allowedDevOrigins

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

On this page