Vite
ViteConf Logo

攜手共建

ViteConf 2025

觀看回放

構建選項 ​

除非另有說明，本節中的選項僅應用於構建。

build.target ​

  • 型別： string | string[]
  • 預設： 'baseline-widely-available'
  • 相關： 瀏覽器相容性

最終產物的瀏覽器相容性目標。預設值是一個特殊的 Vite 值 'baseline-widely-available'，它以 2026-01-01 廣泛支援的 Baseline 瀏覽器為目標。具體而言，它是 ['chrome111', 'edge111', 'firefox114', 'safari16.4']。

另一個特殊值是 'esnext' - 它假設原生支援動態匯入，並且只會執行最少的轉譯。

轉譯是透過 Oxc Transformer 執行的，該值應該是有效的 Oxc Transformer 目標選項。自定義目標可以是 ES 版本（例如 es2015）、帶有版本的瀏覽器（例如 chrome58）或多個目標字串的陣列。

請注意，如果程式碼包含 Oxc 無法安全轉譯的特性，構建過程將輸出警告。更多詳情請參閱 Oxc 文件。

build.modulePreload ​

  • 型別： boolean | { polyfill?: boolean, resolveDependencies?: ResolveModulePreloadDependenciesFn }
  • 預設： { polyfill: true }

預設情況下，會自動注入 模組預載入 Polyfill。該 Polyfill 會自動注入到每個 index.html 入口的代理模組中。如果構建配置為透過 build.rollupOptions.input 使用非 HTML 自定義入口，則需要在你的自定義入口中手動匯入該 Polyfill。

js
import 'vite/modulepreload-polyfill'

注意：該 Polyfill 不適用於 庫模式。如果你需要支援不支援原生動態匯入的瀏覽器，你應該避免在庫中使用它。

可以使用 { polyfill: false } 停用該 Polyfill。

每個動態匯入需要預載入的塊列表由 Vite 計算。預設情況下，載入這些依賴項時將使用包含 base 的絕對路徑。如果 base 是相對路徑（'' 或 './'），則在執行時使用 import.meta.url，以避免依賴於最終部署基礎路徑的絕對路徑。

目前提供實驗性支援，可透過 resolveDependencies 函式對依賴列表及其路徑進行細粒度控制。提供反饋。它需要一個型別為 ResolveModulePreloadDependenciesFn 的函式。

ts
type ResolveModulePreloadDependenciesFn = (
  url: string,
  deps: string[],
  context: {
    hostId: string
    hostType: 'html' | 'js'
  },
) => string[]

resolveDependencies 函式將為每個動態匯入呼叫一次（傳入其依賴的塊列表），也會為入口 HTML 檔案中匯入的每個塊呼叫一次。可以返回一個新的依賴陣列，用於過濾、注入更多依賴或修改它們的路徑。deps 路徑相對於 build.outDir。返回值應為相對於 build.outDir 的路徑。

js
modulePreload
: {
  
resolveDependencies
: (
filename
, 
deps
, { 
hostId
, 
hostType
 }) => {
    return 
deps
.
filter
(condition)
  },
},

解析後的依賴路徑可以使用 experimental.renderBuiltUrl 進一步修改。

build.polyfillModulePreload ​

  • 型別： boolean
  • 預設值： true
  • 已棄用，請改用 build.modulePreload.polyfill

是否自動注入 模組預載入 Polyfill。

build.outDir ​

  • 型別： string
  • 預設： dist

指定輸出目錄（相對於 專案根目錄）。

build.assetsDir ​

  • 型別： string
  • 預設： assets

指定生成資源的存放目錄（相對於 build.outDir。在 庫模式 下不使用此項）。

build.assetsInlineLimit ​

  • 型別： number | ((filePath: string, content: Buffer) => boolean | undefined)
  • 預設： 4096 (4 KiB)

小於此閾值的匯入或引用資源將以內聯 base64 URL 的形式存在，以避免額外的 HTTP 請求。設定為 0 可完全停用內聯。

如果傳入回撥函式，可以返回布林值來選擇開啟或關閉內聯。如果沒有返回值，則應用預設邏輯。

Git LFS 佔位符會自動排除在內聯之外，因為它們不包含所代表檔案的實際內容。

注意

如果你指定了 build.lib，build.assetsInlineLimit 將被忽略，資產將始終內聯，無論檔案大小或是否為 Git LFS 佔位符。

build.cssCodeSplit ​

  • 型別： boolean
  • 預設值： true

啟用/停用 CSS 程式碼分割。啟用時，非同步 JS 塊中匯入的 CSS 將保留為塊，並在獲取該塊時一起獲取。

如果停用，整個專案中的所有 CSS 將被提取到一個單一的 CSS 檔案中。

注意

如果你指定了 build.lib，build.cssCodeSplit 預設為 false。

build.cssTarget ​

  • 型別： string | string[]
  • 預設： 與 build.target 相同

該選項允許使用者為 CSS 壓縮設定與 JavaScript 轉譯不同的瀏覽器目標。

它僅在目標為非主流瀏覽器時使用。一個例子是 Android 微信 WebView，它支援大多數現代 JavaScript 特性，但不支援 CSS 中的 #RGBA 十六進位制顏色表示法。在這種情況下，你需要將 build.cssTarget 設定為 chrome61，以防止 Vite 將 rgba() 顏色轉換為 #RGBA 十六進位制表示法。

build.cssMinify ​

  • 型別： boolean | 'lightningcss' | 'esbuild'
  • 預設： 客戶端構建與 build.minify 相同，SSR 構建預設為 'lightningcss'

此選項允許使用者明確覆蓋 CSS 壓縮，而不依賴於 build.minify，因此你可以分別配置 JS 和 CSS 的壓縮。Vite 預設使用 Lightning CSS 來壓縮 CSS。可以透過 css.lightningcss 進行配置。將此選項設定為 'esbuild' 可改用 esbuild。

當設定為 'esbuild' 時，必須安裝 esbuild。

sh
npm add -D esbuild

build.sourcemap ​

  • 型別： boolean | 'inline' | 'hidden'
  • 預設值： false

生成生產環境的原始碼對映檔案。如果設為 true，將建立一個單獨的 sourcemap 檔案。如果設為 'inline'，sourcemap 將作為資料 URI 追加到輸出檔案中。'hidden' 的作用與 true 類似，但會禁止打包檔案中相應的 sourcemap 註釋。

build.rolldownOptions ​

直接自定義底層的 Rolldown 打包配置。這與從 Rolldown 配置檔案中匯出的選項相同，並將與 Vite 的內部 Rolldown 選項合併。更多詳情請參閱 Rolldown 選項文件。

build.rollupOptions ​

  • 型別： RolldownOptions
  • 已棄用

此選項是 build.rolldownOptions 的別名。請改用 build.rolldownOptions。

build.dynamicImportVarsOptions ​

  • 型別： { include?: string | RegExp | (string | RegExp)[], exclude?: string | RegExp | (string | RegExp)[] }
  • 相關： 動態匯入

是否轉換帶有變數的動態匯入。

build.lib ​

  • 型別： { entry: string | string[] | { [entryAlias: string]: string }, name?: string, formats?: ('es' | 'cjs' | 'umd' | 'iife')[], fileName?: string | ((format: ModuleFormat, entryName: string) => string), cssFileName?: string }
  • 相關： 庫模式

作為庫進行構建。必須提供 entry，因為庫不能使用 HTML 作為入口。name 是暴露的全域性變數，當 formats 包含 'umd' 或 'iife' 時是必需的。預設 formats 為 ['es', 'umd']，如果使用多個入口，則為 ['es', 'cjs']。

fileName 是輸出包檔案的名稱，預設值為 package.json 中的 "name"。它也可以定義為一個函式，接收 format 和 entryName 作為引數，並返回檔名。

如果你的包匯入了 CSS，可以使用 cssFileName 來指定輸出的 CSS 檔名。如果它是字串，預設值與 fileName 相同，否則它也會回退到 package.json 中的 "name"。

vite.config.js
js
import { 
defineConfig
 } from 'vite'

export default 
defineConfig
({
  
build
: {
    
lib
: {
      
entry
: ['src/main.js'],
      
fileName
: (
format
, 
entryName
) => `my-lib-${
entryName
}.${
format
}.js`,
      
cssFileName
: 'my-lib-style',
    },
  },
})

build.license ​

  • 型別： boolean | { fileName?: string }
  • 預設值： false
  • 相關： License

設定為 true 時，構建將生成一個包含所有已打包依賴項許可證的 .vite/license.md 檔案。

如果傳入了 fileName，它將作為相對於 outDir 的許可證檔名。如果以 .json 結尾，將生成原始 JSON 元資料以供進一步處理。例如

json
[
  {
    "name": "dep-1",
    "version": "1.2.3",
    "identifier": "CC0-1.0",
    "text": "CC0 1.0 Universal\n\n..."
  },
  {
    "name": "dep-2",
    "version": "4.5.6",
    "identifier": "MIT",
    "text": "MIT License\n\n..."
  }
]

提示

如果你想在構建的程式碼中引用許可證檔案，可以使用 build.rolldownOptions.output.postBanner 在檔案頂部注入註釋。例如

vite.config.js
js
import { 
defineConfig
 } from 'vite'

export default 
defineConfig
({
  
build
: {
    
license
: true,
    
rolldownOptions
: {
      
output
: {
        
postBanner
:
          '/* See licenses of bundled dependencies at https://example.com/license.md */',
      },
    },
  },
})

build.manifest ​

  • 型別： boolean | string
  • 預設值： false
  • 相關： 後端整合

是否生成一個包含非雜湊資原始檔名與其對應雜湊版本對映的清單檔案，該檔案可供服務端框架用於渲染正確的資源連結。

當值為字串時，它將作為相對於 build.outDir 的清單檔案路徑。當設定為 true 時，路徑將為 .vite/manifest.json。

如果你正在編寫外掛並需要在構建過程中檢查每個輸出塊或資源的關聯 CSS 和靜態資源，你也可以使用 viteMetadata 輸出包元資料 API。

build.ssrManifest ​

是否為生產環境生成 SSR 清單檔案，用於確定樣式連結和資源預載入指令。

當值為字串時，它將作為相對於 build.outDir 的清單檔案路徑。當設定為 true 時，路徑將為 .vite/ssr-manifest.json。

build.ssr ​

生成面向 SSR 的構建。值可以是直接指定 SSR 入口的字串，或者 true（此時需要透過 rollupOptions.input 指定 SSR 入口）。

build.emitAssets ​

  • 型別： boolean
  • 預設值： false

在非客戶端構建期間，靜態資源不會被輸出，因為假設它們將作為客戶端構建的一部分輸出。此選項允許框架在其他環境構建中強制輸出它們。由框架負責在構建後合併這些資源。

build.ssrEmitAssets ​

  • 型別： boolean
  • 預設值： false

在 SSR 構建期間，靜態資源不會被輸出，因為假設它們將作為客戶端構建的一部分輸出。此選項允許框架強制在客戶端和 SSR 構建中都輸出它們。由框架負責在構建後合併這些資源。一旦環境 API (Environment API) 穩定，此選項將被 build.emitAssets 替換。

build.minify ​

  • 型別： boolean | 'oxc' | 'terser' | 'esbuild'
  • 預設： 客戶端構建預設為 'oxc'，SSR 構建預設為 false

設定為 false 以停用壓縮，或指定要使用的壓縮器。預設使用 Oxc Minifier，其速度比 terser 快 30 ~ 90 倍，壓縮效果僅差 0.5 ~ 2%。基準測試

build.minify: 'esbuild' 已棄用，未來將被移除。

注意：在庫模式下使用 'es' 格式時，build.minify 選項不會壓縮空格，因為它會刪除純註釋並破壞 Tree-shaking。

當設定為 'esbuild' 或 'terser' 時，必須分別安裝 esbuild 或 Terser。

sh
npm add -D esbuild
npm add -D terser

build.terserOptions ​

  • 型別： TerserOptions

傳遞給 Terser 的額外 壓縮選項。

此外，你還可以傳遞 maxWorkers: number 選項來指定要開啟的最大工作執行緒數。預設為 CPU 核心數減 1。

build.write ​

  • 型別： boolean
  • 預設值： true

設定為 false 可停用將打包結果寫入磁碟。這主要用於 程式化 build() 呼叫，在寫入磁碟之前需要對打包結果進行後續處理。

build.emptyOutDir ​

  • 型別： boolean
  • 預設： 如果 outDir 在 root 內，則為 true

預設情況下，Vite 在構建時會清空 outDir（如果它在專案根目錄下）。如果 outDir 在根目錄之外，它會發出警告以避免意外刪除重要檔案。你可以顯式設定此選項以取消警告。此選項也可以透過命令列使用 --emptyOutDir。

build.copyPublicDir ​

  • 型別： boolean
  • 預設值： true

預設情況下，Vite 會在構建時將 publicDir 中的檔案複製到 outDir。設定為 false 可停用此行為。

build.reportCompressedSize ​

  • 型別： boolean
  • 預設值： true

啟用/停用 gzip 壓縮大小報告。壓縮大型輸出檔案可能較慢，因此對於大型專案，停用此項可能會提高構建效能。

build.chunkSizeWarningLimit ​

  • 型別： number
  • 預設： 500

塊大小警告限制（以 kB 為單位）。它是根據未壓縮的塊大小進行比較的，因為 JavaScript 本身的大小與執行時間有關。

build.watch ​

設定為 {} 以啟用 rollup 監聽器。這主要用於涉及僅構建外掛或整合流程的情況。

在 Windows Linux 子系統 (WSL) 2 上使用 Vite

在某些情況下，檔案系統監聽在 WSL2 上無法工作。詳見 server.watch。

© 2019-至今 VoidZero Inc. 和 Vite 貢獻者。(b59265c8)