共享選項

除非另有說明，本節中的選項適用於開發 (dev)、構建 (build) 和預覽 (preview)。

root

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

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

詳情請參閱專案根目錄。

base

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

開發或生產環境下的公共基礎路徑。有效值包括：

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

詳情請參閱公共基礎路徑。

mode

型別： string
預設值： 服務啟動時為 'development'，構建時為 'production'

在配置中指定此項將覆蓋服務啟動和構建的預設模式。此值也可以透過命令列 --mode 選項進行覆蓋。

詳情請參閱環境變數和模式。

define

型別： Record<string, any>

定義全域性常量替換。在開發階段，這些條目將被定義為全域性變數；在構建階段，它們將被靜態替換。

Vite 使用 Oxc 的 define 功能執行替換。因此，值表示式必須是包含可 JSON 序列化值（null、boolean、number、string、array 或 object）的字串，或是一個單一的識別符號。對於非字串值，Vite 會自動將其轉換為使用 JSON.stringify 處理後的字串。

示例

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

注意

對於 TypeScript 使用者，請確保在 vite-env.d.ts 檔案中新增型別宣告，以獲得型別檢查和智慧提示。

示例

// 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 }>

定義用於在 import 或 require 語句中替換值的別名。其工作方式類似於 @rollup/plugin-alias。

條目的順序非常重要，因為首先定義的規則會優先應用。

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

透過外掛可以實現更高階的自定義解析。

配合 SSR 使用

如果你已為 SSR 外部化依賴項配置了別名，你可能需要為實際的 node_modules 包設定別名。Yarn 和 pnpm 都支援透過 npm: 字首進行別名設定。

物件格式 (`Record<string, string>`)

物件格式允許將別名指定為鍵，並將相應的值作為實際的匯入值。例如：

resolve: {
  alias: {
    utils: '../../../utils',
    'batman-1.0.0': './joker-1.5.0'
  }
}

陣列格式 (`Array<{ find: string | RegExp, replacement: string }>`)

陣列格式允許將別名指定為物件，這對於複雜的鍵/值對很有用。

resolve: {
  alias: [
    { find: 'utils', replacement: '../../../utils' },
    { find: 'batman-1.0.0', replacement: './joker-1.5.0' },
  ]
}

當 find 是正則表示式時，replacement 可以使用替換模式，例如 $1。例如，要將副檔名替換為其他副檔名，可以使用如下模式：

{ find:/^(.*)\.js$/, replacement: '$1.alias' }

resolve.dedupe

型別： string[]

如果你的應用程式中有重複的依賴項副本（通常是因為 Monorepo 中的提升或連結包所致），請使用此選項強制 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 條件始終會被應用。

此外，在解析樣式匯入（例如 @import 'my-library'）時，會應用 style 條件。對於某些 CSS 預處理器，它們的對應條件也會被應用，即 Sass 的 sass 和 Less 的 less。

resolve.mainFields 不繼承

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

在解析包的入口點時嘗試的 package.json 欄位列表。請注意，此項的優先順序低於從 exports 欄位解析出的條件匯出：如果入口點成功從 exports 解析出來，main 欄位將被忽略。

resolve.extensions

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

嘗試解析省略副檔名的匯入時使用的副檔名列表。請注意，不建議對自定義匯入型別（如 .vue）省略副檔名，因為這會干擾 IDE 和型別支援。

resolve.preserveSymlinks

型別： boolean
預設值： false

啟用此設定後，Vite 將透過原始檔案路徑（即不跟隨符號連結的路徑）而不是真實檔案路徑（即跟隨符號連結後的路徑）來確定檔案標識。

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

resolve.tsconfigPaths

型別： boolean
預設值： false

啟用 tsconfig 路徑解析功能。tsconfig.json 中的 paths 選項將被用於解析匯入。詳情請參閱特性。

html.cspNonce

型別： string
相關： 內容安全策略 (CSP)

生成 script / style 標籤時使用的 nonce 值佔位符。設定此值還將生成一個帶有 nonce 值的元標籤 (meta tag)。

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 時，此選項無效。如果已啟用 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
- 如果已安裝，則使用 sass-embedded，否則使用 sass。為獲得最佳效能，建議安裝 sass-embedded 包。
- 選項
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: {
        importers: [
          // ...
        ],
      },
    },
  },
})

css.preprocessorOptions[extension].additionalData

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

此選項可用於為每個樣式內容注入額外程式碼。請注意，如果你注入的是實際的樣式而非僅僅是變數，這些樣式將在最終產物中重複出現。

示例

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

匯入檔案

由於相同的程式碼被新增到不同目錄的檔案中，相對路徑將無法正確解析。請改用絕對路徑或別名。

css.preprocessorMaxWorkers

型別： number | true
預設值： true

指定 CSS 預處理器可以使用的最大執行緒數。true 表示最多可使用 CPU 核心數減 1。設定為 0 時，Vite 將不會建立任何工作執行緒，而是在主執行緒中執行預處理器。

根據預處理器的選項，即使未將此選項設定為 0，Vite 也可能在主執行緒中執行預處理器。

css.devSourcemap

實驗性： 提供反饋
型別： boolean
預設值： false

是否在開發階段啟用 sourcemaps。

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 時才會進行序列化。

oxc

型別： OxcOptions | false

OxcOptions 擴充套件了 Oxc Transformer 的選項。最常見的使用場景是自定義 JSX。

export default defineConfig({
  oxc: {
    jsx: {
      runtime: 'classic',
      pragma: 'h',
      pragmaFrag: 'Fragment',
    },
  },
})

預設情況下，Oxc 的轉換應用於 ts、jsx 和 tsx 檔案。你可以使用 oxc.include 和 oxc.exclude 來自定義此行為，它們可以是正則表示式、picomatch 模式或它們的陣列。

此外，你還可以使用 oxc.jsxInject 為每個經 Oxc 轉換的檔案自動注入 JSX 輔助匯入。

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

設定為 false 可停用 Oxc 轉換。

esbuild

型別： ESBuildOptions | false
已棄用

此選項在內部已轉換為 oxc 選項。請改用 oxc 選項。

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 | false
預設值： root

載入 .env 檔案的目錄。可以是絕對路徑，也可以是相對於專案根目錄的路徑。設定為 false 將停用 .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)，還是自定義應用（SSR 和具有自定義 HTML 處理的框架）。

'spa'：包含 HTML 中介軟體並使用 SPA 回退。在預覽模式下，透過 single: true 配置 sirv。
'mpa'：包含 HTML 中介軟體。
'custom'：不包含 HTML 中介軟體。

在 Vite 的 SSR 指南中瞭解更多。相關：server.middlewareMode。

devtools

實驗性： 提供反饋
型別： boolean | DevToolsConfig
預設值： false

啟用 DevTools 整合以視覺化內部狀態和進行構建分析。確保 @vitejs/devtools 已作為依賴項安裝。此功能目前僅在構建模式下支援。

詳見 Vite DevTools。

future

型別： Record<string, 'warn' | undefined>
相關： 破壞性變更

啟用未來的破壞性變更，為平穩遷移到 Vite 的下一個主要版本做好準備。列表可能會隨著新特性的開發隨時進行更新、新增或刪除。

有關可能選項的詳細資訊，請參閱破壞性變更頁面。

共享選項 ​

root ​

base ​

mode ​

define ​

plugins ​

publicDir ​

cacheDir ​

resolve.alias ​

物件格式 (Record<string, string>) ​

陣列格式 (Array<{ find: string | RegExp, replacement: string }>) ​

resolve.dedupe ​

resolve.conditions 不繼承 ​

resolve.mainFields 不繼承 ​

resolve.extensions ​

resolve.preserveSymlinks ​

resolve.tsconfigPaths ​

html.cspNonce ​

css.modules ​

css.postcss ​

css.preprocessorOptions ​

css.preprocessorOptions[extension].additionalData ​

css.preprocessorMaxWorkers ​

css.devSourcemap ​

css.transformer ​

css.lightningcss ​

json.namedExports ​

json.stringify ​

oxc ​

esbuild ​

assetsInclude ​

logLevel ​

customLogger ​

clearScreen ​

envDir ​

envPrefix ​

appType ​

devtools ​

future ​