共用選項

除非另有說明，否則本節中的選項適用於所有開發、建置和預覽。

root

類型： string
預設值： process.cwd()

專案根目錄（index.html 所在的目錄）。可以是絕對路徑，也可以是相對於目前工作目錄的路徑。

有關詳細資訊，請參閱專案根目錄。

base

類型： string
預設值： /
相關： server.origin

在開發或生產環境中提供的基本公開路徑。有效值包括：

絕對 URL 路徑名稱，例如 /foo/
完整 URL，例如 https://bar.com/foo/（原點部分在開發環境中不會使用，因此該值與 /foo/ 相同）
空字串或 ./（用於嵌入式部署）

有關詳細資訊，請參閱公開基本路徑。

mode

類型： string
預設值： 伺服器為 'development'，建置為 'production'

在設定中指定此值將覆蓋伺服器和建置的預設模式。此值也可以透過命令列 --mode 選項覆蓋。

有關詳細資訊，請參閱環境變數和模式。

define

類型： Record<string, any>

定義全域常數取代。在開發期間，這些項目將被定義為全域變數，並在建置期間進行靜態取代。

Vite 使用 esbuild defines 來執行取代，因此值表達式必須是一個包含 JSON 可序列化值（null、布林值、數字、字串、陣列或物件）或單一識別符的字串。對於非字串值，Vite 會使用 JSON.stringify 自動將其轉換為字串。

範例

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify('v1.0.0'),
    __API_URL__: 'window.__backend_api_url',
  },
})

注意

對於 TypeScript 使用者，請務必在 env.d.ts 或 vite-env.d.ts 檔案中新增類型宣告，以取得類型檢查和 Intellisense。

範例

// vite-env.d.ts
declare const __APP_VERSION__: string

plugins

類型： (Plugin | Plugin[] | Promise<Plugin | Plugin[]>)[]

要使用的外掛陣列。假值外掛會被忽略，外掛陣列會被展平。如果傳回 Promise，則會在執行之前解析。有關 Vite 外掛的詳細資訊，請參閱外掛 API。

publicDir

類型： string | false
預設值： "public"

要作為純靜態資產提供的目錄。此目錄中的檔案在開發期間在 / 下提供，並在建置期間複製到 outDir 的根目錄，並且始終按原樣提供或複製，不進行轉換。該值可以是絕對檔案系統路徑或相對於專案根目錄的路徑。

將 publicDir 定義為 false 會停用此功能。

有關詳細資訊，請參閱public 目錄。

cacheDir

類型： string
預設值： "node_modules/.vite"

儲存快取檔案的目錄。此目錄中的檔案是預先捆綁的依賴項或 vite 產生的一些其他快取檔案，可以提高效能。您可以使用 --force 標誌或手動刪除該目錄來重新產生快取檔案。該值可以是絕對檔案系統路徑或相對於專案根目錄的路徑。如果未偵測到 package.json，則預設為 .vite。

resolve.alias

類型：Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

將作為其entries 選項傳遞給 @rollup/plugin-alias。可以是物件或 { find, replacement, customResolver } 配對的陣列。

當使用別名指向檔案系統路徑時，請始終使用絕對路徑。相對別名值將按原樣使用，而不會解析為檔案系統路徑。

更進階的自訂解析可以透過外掛實現。

與 SSR 一起使用

如果您已為SSR 外部化依賴項設定別名，您可能需要將實際的 node_modules 套件設定別名。 Yarn 和 pnpm 都支援透過 npm: 前綴設定別名。

resolve.dedupe

類型： string[]

如果您的應用程式中有相同依賴項的重複副本（可能是由於 monorepos 中的提升或連結套件），請使用此選項強制 Vite 始終將列出的依賴項解析為相同副本（來自專案根目錄）。

SSR + ESM

對於 SSR 建置，重複資料刪除不適用於從 build.rollupOptions.output 設定的 ESM 建置輸出。一種變通方法是使用 CJS 建置輸出，直到 ESM 對模組載入有更好的外掛支援。

resolve.conditions

類型： string[]
預設值： ['module', 'browser', 'development|production'] (defaultClientConditions)

解析套件中的條件匯出時允許的其他條件。

具有條件匯出的套件在其 package.json 中可能具有以下 exports 欄位

json

{
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}

在這裡，import 和 require 是「條件」。條件可以巢狀，應從最特定到最不特定指定。

development|production 是一個特殊值，根據 process.env.NODE_ENV 的值替換為 production 或 development。當 process.env.NODE_ENV === 'production' 時，它會替換為 production，否則替換為 development。

請注意，如果滿足要求，則始終會套用 import、require、default 條件。

解析子路徑匯出

以 "/" 結尾的匯出金鑰已由 Node 棄用，可能無法正常運作。請聯繫套件作者以改用 * 子路徑模式。

resolve.mainFields

類型： string[]
預設值： ['browser', 'module', 'jsnext:main', 'jsnext'] (defaultClientMainFields)

解析套件的進入點時，要在 package.json 中嘗試的欄位列表。請注意，這比從 exports 欄位解析的條件匯出具有較低的優先順序：如果從 exports 成功解析進入點，則會忽略主要欄位。

resolve.extensions

類型： string[]
預設值： ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']

要嘗試省略擴展名的匯入的檔案擴展名列表。請注意，不建議省略自訂匯入類型（例如 .vue）的擴展名，因為它可能會干擾 IDE 和類型支援。

resolve.preserveSymlinks

類型： boolean
預設值： false

啟用此設定會導致 vite 透過原始檔案路徑（即不追蹤符號連結的路徑）而不是實際檔案路徑（即追蹤符號連結之後的路徑）來判斷檔案身分。

相關： esbuild#preserve-symlinks, webpack#resolve.symlinks

html.cspNonce

類型： string
相關： 內容安全政策 (CSP)

將在產生腳本/樣式標籤時使用的 nonce 值預留位置。設定此值也會產生一個具有 nonce 值的 meta 標籤。

css.modules

類型

interface CSSModulesOptions {
  getJSON?: (
    cssFileName: string,
    json: Record<string, string>,
    outputFileName: string,
  ) => void
  scopeBehaviour?: 'global' | 'local'
  globalModulePaths?: RegExp[]
  exportGlobals?: boolean
  generateScopedName?:
    | string
    | ((name: string, filename: string, css: string) => string)
  hashPrefix?: string
  /**
   * default: undefined
   */
  localsConvention?:
    | 'camelCase'
    | 'camelCaseOnly'
    | 'dashes'
    | 'dashesOnly'
    | ((
        originalClassName: string,
        generatedClassName: string,
        inputFile: string,
      ) => string)
}

設定 CSS 模組行為。這些選項會傳遞給 postcss-modules。

當使用 Lightning CSS 時，此選項不會有任何作用。如果啟用，應改用 css.lightningcss.cssModules。

css.postcss

類型： string | (postcss.ProcessOptions & { plugins?: postcss.AcceptedPlugin[] })

內聯 PostCSS 配置或用於搜尋 PostCSS 配置的自訂目錄（預設為專案根目錄）。

對於內聯 PostCSS 配置，它期望與 postcss.config.js 相同的格式。但對於 plugins 屬性，只能使用陣列格式。

搜尋使用 postcss-load-config 進行，並且僅載入支援的設定檔名稱。預設情況下，不會搜尋工作區根目錄（或如果找不到工作區，則為專案根目錄）之外的設定檔。如果需要，您可以指定根目錄之外的自訂路徑來載入特定的設定檔。

請注意，如果提供了內聯配置，Vite 將不會搜尋其他 PostCSS 配置來源。

css.preprocessorOptions

類型： Record<string, object>

指定要傳遞給 CSS 預處理器的選項。檔案副檔名會用作選項的鍵。每個預處理器支援的選項可以在它們各自的文件中找到。

sass/scss
- 使用 api: "modern-compiler" | "modern" | "legacy" 選擇要使用的 sass API（如果安裝了 sass-embedded，則預設為 "modern-compiler"，否則為 "modern"）。為了獲得最佳效能，建議使用 api: "modern-compiler" 和 sass-embedded 套件。"legacy" API 已被棄用，將在 Vite 7 中移除。
- 選項 (modern)
- 選項 (legacy).
less: 選項。
styl/stylus：僅支援 define，可以作為物件傳遞。

範例

export default defineConfig({
  css: {
    preprocessorOptions: {
      less: {
        math: 'parens-division',
      },
      styl: {
        define: {
          $specialColor: new stylus.nodes.RGBA(51, 197, 255, 1),
        },
      },
      scss: {
        api: 'modern-compiler', // or "modern", "legacy"
        importers: [
          // ...
        ],
      },
    },
  },
})

css.preprocessorOptions[extension].additionalData

類型： string | ((source: string, filename: string) => (string | { content: string; map?: SourceMap }))

此選項可用於為每個樣式內容注入額外的程式碼。請注意，如果您包含實際的樣式而不僅僅是變數，這些樣式將會在最終的 bundle 中重複。

範例

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `$injectedColor: orange;`,
      },
    },
  },
})

css.preprocessorMaxWorkers

實驗性： 提供回饋
類型： number | true
預設值： 0（不建立任何 worker，在主執行緒中執行）

如果設定此選項，CSS 預處理器將在可能的情況下在 worker 中執行。true 表示 CPU 數量減 1。

css.devSourcemap

實驗性： 提供回饋
類型： boolean
預設值： false

是否在開發期間啟用 sourcemap。

css.transformer

實驗性： 提供回饋
類型： 'postcss' | 'lightningcss'
預設值： 'postcss'

選擇用於 CSS 處理的引擎。請查看 Lightning CSS 以獲取更多資訊。

重複的 @import

請注意，postcss (postcss-import) 在處理與瀏覽器重複的 @import 時有不同的行為。請參閱 postcss/postcss-import#462。

css.lightningcss

實驗性： 提供回饋
類型

import type {
  CSSModulesConfig,
  Drafts,
  Features,
  NonStandard,
  PseudoClasses,
  Targets,
} from 'lightningcss'

{
  targets?: Targets
  include?: Features
  exclude?: Features
  drafts?: Drafts
  nonStandard?: NonStandard
  pseudoClasses?: PseudoClasses
  unusedSymbols?: string[]
  cssModules?: CSSModulesConfig,
  // ...
}

配置 Lightning CSS。完整的轉換選項可以在 Lightning CSS 儲存庫中找到。

json.namedExports

類型： boolean
預設值： true

是否支援從 .json 檔案匯入具名匯入。

json.stringify

類型： boolean | 'auto'
預設值： 'auto'

如果設定為 true，匯入的 JSON 將被轉換為 export default JSON.parse("...")，這比物件字面值更有效能，尤其是在 JSON 檔案很大時。

如果設定為 'auto'，則只有當資料大於 10kB 時才會字串化資料。

esbuild

類型： ESBuildOptions | false

ESBuildOptions 擴展了 esbuild 自己的轉換選項。最常見的用例是自訂 JSX。

export default defineConfig({
  esbuild: {
    jsxFactory: 'h',
    jsxFragment: 'Fragment',
  },
})

預設情況下，esbuild 會應用於 ts、jsx 和 tsx 檔案。您可以使用 esbuild.include 和 esbuild.exclude 來客製化此行為，它們可以是 regex、picomatch 模式，或是兩者的陣列。

此外，您也可以使用 esbuild.jsxInject 為每個由 esbuild 轉換的檔案自動注入 JSX 輔助匯入。

export default defineConfig({
  esbuild: {
    jsxInject: `import React from 'react'`,
  },
})

當 build.minify 為 true 時，預設會應用所有縮小優化。若要停用它的某些方面，請將 esbuild.minifyIdentifiers、esbuild.minifySyntax 或 esbuild.minifyWhitespace 選項設定為 false。請注意，esbuild.minify 選項不能用於覆蓋 build.minify。

設定為 false 以停用 esbuild 轉換。

assetsInclude

類型： string | RegExp | (string | RegExp)[]
相關連結： 靜態資源處理

指定其他要被視為靜態資源的 picomatch 模式，以便

當從 HTML 中引用或透過 fetch 或 XHR 直接請求時，它們將被排除在插件轉換管道之外。
從 JS 匯入它們將會返回它們解析後的 URL 字串（如果您有 enforce: 'pre' 插件以不同的方式處理資源類型，則可以覆寫此行為）。

內建的資源類型清單可以在這裡找到。

範例

export default defineConfig({
  assetsInclude: ['**/*.gltf'],
})

logLevel

類型： 'info' | 'warn' | 'error' | 'silent'

調整主控台輸出詳細程度。預設值為 'info'。

customLogger

類型

interface Logger {
  info(msg: string, options?: LogOptions): void
  warn(msg: string, options?: LogOptions): void
  warnOnce(msg: string, options?: LogOptions): void
  error(msg: string, options?: LogErrorOptions): void
  clearScreen(type: LogType): void
  hasErrorLogged(error: Error | RollupError): boolean
  hasWarned: boolean
}

使用自訂記錄器記錄訊息。您可以使用 Vite 的 createLogger API 來獲取預設記錄器並自訂它，例如，變更訊息或篩選掉某些警告。

import { createLogger
, defineConfig
 } from 'vite'

const logger
 = createLogger
()
const loggerWarn
 = logger
.warn


logger
.warn
 = (msg
, options
) => {
  // Ignore empty CSS files warning
  if (msg
.includes
('vite:css') && msg
.includes
(' is empty')) return
  loggerWarn
(msg
, options
)
}

export default defineConfig
({
  customLogger
: logger
,
})

clearScreen

類型： boolean
預設值： true

設定為 false 可防止 Vite 在記錄某些訊息時清除終端機畫面。透過命令列，請使用 --clearScreen false。

envDir

類型： string
預設值： root

載入 .env 檔案的目錄。可以是絕對路徑，或是相對於專案根目錄的路徑。

請參閱這裡以獲取有關環境檔案的更多資訊。

envPrefix

類型： string | string[]
預設值： VITE_

以 envPrefix 開頭的環境變數將透過 import.meta.env 暴露給您的客戶端原始碼。

安全注意事項

envPrefix 不應設定為 ''，這會暴露您所有的環境變數並導致敏感資訊意外洩漏。Vite 在偵測到 '' 時會拋出錯誤。

如果您想暴露一個沒有前綴的變數，可以使用 define 來暴露它。

define: {
  'import.meta.env.ENV_VARIABLE': JSON.stringify(process.env.ENV_VARIABLE)
}

appType

類型： 'spa' | 'mpa' | 'custom'
預設值： 'spa'

您的應用程式是單頁應用程式 (SPA)、多頁應用程式 (MPA)，還是自訂應用程式（具有自訂 HTML 處理的 SSR 和框架）。

'spa'：包含 HTML 中介軟體並使用 SPA 後備。在預覽中，使用 single: true 配置 sirv
'mpa'：包含 HTML 中介軟體
'custom'：不包含 HTML 中介軟體

在 Vite 的 SSR 指南中了解更多資訊。相關連結：server.middlewareMode。

future

類型： Record<string, 'warn' | undefined>
相關連結： 重大變更

啟用未來的重大變更，以便為順利遷移到下一個主要版本的 Vite 做準備。該清單可能會隨時更新、新增或刪除，因為會開發新功能。

請參閱重大變更頁面，了解可能選項的詳細資訊。

共用選項 ​

root ​

base ​

mode ​

define ​

plugins ​

publicDir ​

cacheDir ​

resolve.alias ​

resolve.dedupe ​

resolve.conditions ​

resolve.mainFields ​

resolve.extensions ​

resolve.preserveSymlinks ​

html.cspNonce ​

css.modules ​

css.postcss ​

css.preprocessorOptions ​

css.preprocessorOptions[extension].additionalData ​

css.preprocessorMaxWorkers ​

css.devSourcemap ​

css.transformer ​

css.lightningcss ​

json.namedExports ​

json.stringify ​

esbuild ​

assetsInclude ​

logLevel ​

customLogger ​

clearScreen ​

envDir ​

envPrefix ​

appType ​

future ​