配置 Vite

當從命令列執行 vite 時，Vite 會自動嘗試解析專案根目錄中的 vite.config.js 配置檔案（也支援其他 JS 和 TS 副檔名）。

最基本的配置檔案如下所示：

vite.config.js

export default {
  // config options
}

注意：即使專案沒有使用原生的 Node ESM（例如 package.json 中沒有 "type": "module"），Vite 也支援在配置檔案中使用 ES 模組語法。在這種情況下，配置檔案會在載入前自動預處理。

你也可以透過 --config CLI 選項顯式指定要使用的配置檔案（路徑相對於 cwd 解析）：

bash

vite --config my-config.js

觀看 Scrimba 上的互動式教程

配置載入

預設情況下，Vite 使用 Rolldown 將配置檔案打包成臨時檔案並載入。這在 Monorepo 中匯入 TypeScript 檔案時可能會導致問題。如果遇到此類問題，你可以指定 --configLoader runner 來改用模組執行器 (module runner)，它不會建立臨時配置，而是會即時轉換檔案。注意，模組執行器不支援配置檔案中的 CJS，但外部 CJS 包應能正常工作。

另外，如果你使用的環境支援 TypeScript（例如 node --experimental-strip-types），或者你只編寫純 JavaScript，你可以指定 --configLoader native 使用環境的原生執行時來載入配置檔案。注意，配置檔案匯入的模組如有更新將不會被檢測到，因此不會自動重啟 Vite 伺服器。

配置智慧提示

由於 Vite 自帶 TypeScript 型別定義，你可以利用 IDE 的智慧提示功能，透過 JSDoc 型別提示來實現：

/** @type {import('vite').UserConfig} */
export default {
  // ...
}

或者，你可以使用 defineConfig 輔助函式，它無需 JSDoc 註解即可提供智慧提示：

import { defineConfig } from 'vite'

export default defineConfig({
  // ...
})

Vite 也支援 TypeScript 配置檔案。你可以將 vite.config.ts 與上述 defineConfig 輔助函式一起使用，或者使用 satisfies 運算子：

import type { UserConfig } from 'vite'

export default {
  // ...
} satisfies UserConfig

條件配置

如果配置需要根據命令（serve 或 build）、所使用的模式 (mode)、是否為 SSR 構建 (isSsrBuild) 或是否正在預覽構建 (isPreview) 來有條件地確定選項，則可以匯出一個函式：

export default defineConfig
(({ command
, mode
, isSsrBuild
, isPreview
 }) => {
  if (command
 === 'serve') {
    return {
      // dev specific config
    }
  } else {
    // command === 'build'
    return {
      // build specific config
    }
  }
})

需要注意的是，在 Vite 的 API 中，command 的值在開發階段（CLI 命令 vite、vite dev 和 vite serve 均為別名）為 serve；在生產構建時（vite build）則為 build。

isSsrBuild 和 isPreview 是額外的可選標誌，用於分別區分 build 和 serve 命令的具體型別。一些載入 Vite 配置的工具可能不支援這些標誌，並會傳遞 undefined。因此，建議明確與 true 或 false 進行比較。

非同步配置

如果配置需要呼叫非同步函式，可以匯出一個非同步函式。此非同步函式也可以透過 defineConfig 包裝，以獲得更好的智慧提示支援：

export default defineConfig
(async ({ command
, mode
 }) => {
  const data
 = await asyncFunction()
  return {
    // vite config
  }
})

在配置中使用環境變數

在配置評估時可用的環境變數僅限於當前程序環境 (process.env) 中已有的變數。Vite 會刻意延遲載入任何 .env* 檔案，直到使用者配置被解析完成，因為要載入的檔案集取決於 root 和 envDir 等配置選項，以及最終的 mode。

這意味著：在 vite.config.* 執行期間，定義在 .env、.env.local、.env.[mode] 或 .env.[mode].local 中的變數不會自動注入到 process.env 中。它們會在稍後自動載入，並透過 import.meta.env 暴露給應用程式程式碼（預設帶有 VITE_ 字首過濾器），正如環境變數和模式文件所述。因此，如果你只需要將 .env* 檔案中的值傳遞給應用，則無需在配置檔案中進行任何額外呼叫。

然而，如果 .env* 檔案中的值必須影響配置本身（例如設定 server.port、有條件地啟用外掛或計算 define 替換），你可以使用匯出的 loadEnv 輔助函式手動載入它們。

import { defineConfig
, loadEnv
 } from 'vite'

export default defineConfig
(({ mode
 }) => {
  // Load env file based on `mode` in the current working directory.
  // Set the third parameter to '' to load all env regardless of the
  // `VITE_` prefix.
  const env
 = loadEnv
(mode
, process
.cwd
(), '')
  return {
    define
: {
      // Provide an explicit app-level constant derived from an env var.
      __APP_ENV__
: JSON
.stringify
(env
.APP_ENV
),
    },
    // Example: use an env var to set the dev server port conditionally.
    server
: {
      port
: env
.APP_PORT
 ? Number
(env
.APP_PORT
) : 5173,
    },
  }
})

在 VS Code 中除錯配置檔案

在使用預設的 --configLoader bundle 行為時，Vite 會將生成的臨時配置檔案寫入 node_modules/.vite-temp 資料夾。在 Vite 配置檔案中設定斷點除錯時，會發生“找不到檔案”錯誤。要修復此問題，請將以下配置新增到 .vscode/settings.json：

json

{
  "debug.javascript.terminalOptions": {
    "resolveSourceMapLocations": [
      "${workspaceFolder}/**",
      "!**/node_modules/**",
      "**/node_modules/.vite-temp/**"
    ]
  }
}

配置 Vite ​

配置智慧提示 ​

條件配置 ​

非同步配置 ​

在配置中使用環境變數 ​