Vite
ViteConf Logo

攜手共建

ViteConf 2025

觀看回放

從 v7 遷移 ​

如果您是從 rolldown-vite（Rolldown 整合 Vite 的技術預覽版，適用於 v6 和 v7）進行遷移，則僅標題中帶有 NRV 的部分適用。

預設瀏覽器目標變更 NRV ​

build.target 和 'baseline-widely-available' 的預設瀏覽器值已更新為更新的瀏覽器版本

  • Chrome 107 → 111
  • Edge 107 → 111
  • Firefox 104 → 114
  • Safari 16.0 → 16.4

這些瀏覽器版本與截至 2026-01-01 的 基準廣泛可用 (Baseline Widely Available) 功能集一致。換句話說，它們都是在大約兩年半前釋出的。

Rolldown ​

Vite 8 使用基於 Rolldown 和 Oxc 的工具，而不是 esbuild 和 Rollup。

漸進式遷移 ​

rolldown-vite 包在 Vite 7 中實現了 Rolldown，但不包含其他 Vite 8 的更改。這可以用作遷移到 Vite 8 的中間步驟。請參閱 Vite 7 文件中的 Rolldown 整合指南，以從 Vite 7 切換到 rolldown-vite。

對於從 rolldown-vite 遷移到 Vite 8 的使用者，您可以撤銷 package.json 中的依賴項更改並更新到 Vite 8

json
{
  "devDependencies": {
    "vite": "npm:rolldown-vite@7.2.2"
    "vite": "^8.0.0"
  }
}

依賴項最佳化器現在使用 Rolldown ​

Rolldown 現在用於依賴項最佳化，而不是 esbuild。為了向後相容，Vite 仍然支援 optimizeDeps.esbuildOptions，並會自動將其轉換為 optimizeDeps.rolldownOptions。optimizeDeps.esbuildOptions 現已被棄用，將來會被移除，我們建議您遷移到 optimizeDeps.rolldownOptions。

以下選項會自動轉換

您可以從 configResolved 鉤子獲取由相容層設定的選項

js
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.optimizeDeps.rolldownOptions)
  },
},

由 Oxc 進行的 JavaScript 轉換 ​

Oxc 現在用於 JavaScript 轉換，而不是 esbuild。為了向後相容，Vite 仍然支援 esbuild 選項，並會自動將其轉換為 oxc。esbuild 現已被棄用，將來會被移除，我們建議您遷移到 oxc。

以下選項會自動轉換

Oxc 不支援 esbuild.supported 選項。如果您需要此選項，請參閱 oxc-project/oxc#15373。

您可以從 configResolved 鉤子獲取由相容層設定的選項

js
const plugin = {
  name: 'log-config',
  configResolved(config) {
    console.log('options', config.oxc)
  },
},

目前，Oxc 轉換器不支援降級原生裝飾器（native decorators），因為我們正在等待規範的進展，請參閱 (oxc-project/oxc#9170)。

降級原生裝飾器的變通方法

您可以暫時使用 Babel 或 SWC 來降級原生裝飾器。雖然 SWC 比 Babel 快，但它不支援 esbuild 所支援的最新裝飾器規範。

裝飾器規範在達到 stage 3 後已經更新了多次。每個工具支援的版本如下：

  • "2023-11" (esbuild、TypeScript 5.4+ 和 Babel 支援此版本)
  • "2023-05" (TypeScript 5.2+ 支援此版本)
  • "2023-01" (TypeScript 5.0+ 支援此版本)
  • "2022-03" (SWC 支援此版本)

請參閱 Babel 裝飾器版本指南，瞭解各版本之間的差異。

使用 Babel

bash
$ npm install -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ yarn add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ pnpm add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ bun add -D @rolldown/plugin-babel @babel/plugin-proposal-decorators
bash
$ deno add -D npm:@rolldown/plugin-babel npm:@babel/plugin-proposal-decorators
vite.config.ts
ts
import { defineConfig } from 'vite'
import babel from '@rolldown/plugin-babel'

function decoratorPreset(options: Record<string, unknown>) {
  return {
    preset: () => ({
      plugins: [['@babel/plugin-proposal-decorators', options]],
    }),
    rolldown: {
      // Only run this transform if the file contains a decorator.
      filter: {
        code: '@',
      },
    },
  }
}

export default defineConfig({
  plugins: [babel({ presets: [decoratorPreset({ version: '2023-11' })] })],
})

使用 SWC

bash
$ npm install -D @rollup/plugin-swc @swc/core
bash
$ yarn add -D @rollup/plugin-swc @swc/core
bash
$ pnpm add -D @rollup/plugin-swc @swc/core
bash
$ bun add -D @rollup/plugin-swc @swc/core
bash
$ deno add -D npm:@rollup/plugin-swc npm:@swc/core
js
import { defineConfig, withFilter } from 'vite'

export default defineConfig({
  // ...
  plugins: [
    withFilter(
      swc({
        swc: {
          jsc: {
            parser: { decorators: true, decoratorsBeforeExport: true },
            // NOTE: SWC doesn't support the '2023-11' version yet.
            transform: { decoratorVersion: '2022-03' },
          },
        },
      }),
      // Only run this transform if the file contains a decorator.
      { transform: { code: '@' } },
    ),
  ],
})

esbuild 後備方案 ​

esbuild 不再被 Vite 直接使用，現在是一個可選依賴項。如果您使用的外掛呼叫了 transformWithEsbuild 函式，您需要將 esbuild 安裝為 devDependency。transformWithEsbuild 函式已被棄用，將來會被移除。我們建議改為遷移到新的 transformWithOxc 函式。

由 Oxc 進行的 JavaScript 壓縮 ​

Oxc Minifier 現在用於 JavaScript 壓縮，而不是 esbuild。您可以使用已棄用的 build.minify: 'esbuild' 選項切換回 esbuild。此配置選項將來會被移除，並且您需要將 esbuild 安裝為 devDependency，因為 Vite 不再直接依賴 esbuild。

如果您過去使用 esbuild.minify* 選項來控制壓縮行為，現在可以使用 build.rolldownOptions.output.minify 代替。如果您過去使用 esbuild.drop 選項，現在可以使用 build.rolldownOptions.output.minify.compress.drop* 選項。

屬性混淆（Property mangling）及其相關選項（mangleProps, reserveProps, mangleQuoted, mangleCache）不受 Oxc 支援。如果您需要這些選項，請參閱 oxc-project/oxc#15375。

esbuild 和 Oxc Minifier 對原始碼的假設略有不同。如果您懷疑壓縮器導致程式碼損壞，可以在此處對比這些假設：

如果您發現 JavaScript 應用在壓縮方面有任何問題，請務必報告。

由 Lightning CSS 進行的 CSS 壓縮 ​

Lightning CSS 現在預設用於 CSS 壓縮。您可以使用 build.cssMinify: 'esbuild' 選項切換回 esbuild。請注意，您需要安裝 esbuild 作為 devDependency。

Lightning CSS 支援更好的語法降級，您的 CSS 包體積可能會略有增加。

一致的 CommonJS 互操作性 ​

現在，從 CommonJS (CJS) 模組進行的 default 匯入以一致的方式處理。

如果滿足以下任一條件，default 匯入即為所匯入 CJS 模組的 module.exports 值。否則，default 匯入為所匯入 CJS 模組的 module.exports.default 值：

  • 匯入者是 .mjs 或 .mts 檔案。
  • 匯入者最近的 package.json 中 type 欄位設定為 module。
  • 所匯入 CJS 模組的 module.exports.__esModule 值未設定為 true。
之前的行為

在開發環境下，如果滿足以下任一條件，default 匯入為所匯入 CJS 模組的 module.exports 值。否則，default 匯入為所匯入 CJS 模組的 module.exports.default 值：

  • 匯入者被包含在依賴項最佳化中且為 .mjs 或 .mts 檔案。
  • 匯入者被包含在依賴項最佳化中且匯入者最近的 package.json 中 type 欄位設定為 module。
  • 所匯入 CJS 模組的 module.exports.__esModule 值未設定為 true。

在構建環境下，條件為：

  • 所匯入 CJS 模組的 module.exports.__esModule 值未設定為 true。
  • module.exports 的 default 屬性不存在.

(假設 build.commonjsOptions.defaultIsModuleExports 未從預設值 'auto' 修改)

有關此問題的更多詳細資訊，請參閱 Rolldown 文件：Ambiguous default import from CJS modules - Bundling CJS | Rolldown。

此更改可能會破壞某些匯入 CJS 模組的現有程式碼。您可以使用已棄用的 legacy.inconsistentCjsInterop: true 選項暫時恢復之前的行為。如果您發現有受此更改影響的包，請向包作者報告或提交 Pull Request。請確保連結到上面的 Rolldown 文件，以便作者瞭解上下文。

移除了使用格式嗅探的模組解析 ​

當 package.json 中同時存在 browser 和 module 欄位時，Vite 過去會根據檔案內容解析欄位，併為瀏覽器選擇 ESM 檔案。引入此機制是因為一些包使用 module 欄位指向 Node.js 的 ESM 檔案，而另一些包使用 browser 欄位指向瀏覽器的 UMD 檔案。鑑於現代 exports 欄位解決了此問題並已被許多包採用，Vite 不再使用此啟發式方法，始終遵循 resolve.mainFields 選項的順序。如果您依賴於此行為，可以使用 resolve.alias 選項將該欄位對映到所需檔案，或使用包管理器打補丁（例如 patch-package, pnpm patch）。

外部化模組的 Require 呼叫 ​

外部化模組的 require 呼叫現在保留為 require 呼叫，而不會轉換為 import 語句。這是為了保留 require 呼叫的語義。如果您想將它們轉換為 import 語句，可以使用 Rolldown 內建的 esmExternalRequirePlugin（從 vite 中重新匯出）。

js
import { defineConfig, esmExternalRequirePlugin } from 'vite'

export default defineConfig({
  // ...
  plugins: [
    esmExternalRequirePlugin({
      external: ['react', 'vue', /^node:/],
    }),
  ],
})

有關詳細資訊，請參閱 Rolldown 文件：require external modules - Bundling CJS | Rolldown。

UMD / IIFE 中的 import.meta.url ​

import.meta.url 不再在 UMD / IIFE 輸出格式中被 polyfill。預設情況下，它將被替換為 undefined。如果您更喜歡之前的行為，可以使用 define 選項配合 build.rolldownOptions.output.intro 選項。有關詳細資訊，請參閱 Rolldown 文件：Well-known import.meta properties - Non ESM Output Formats | Rolldown。

移除了 build.rollupOptions.watch.chokidar 選項 ​

build.rollupOptions.watch.chokidar 選項已被移除。請遷移到 build.rolldownOptions.watch.watcher 選項。

移除了物件形式的 build.rollupOptions.output.manualChunks 並棄用了函式形式 ​

物件形式的 output.manualChunks 選項不再支援。函式形式的 output.manualChunks 已被棄用。Rolldown 擁有更靈活的 codeSplitting 選項。有關 codeSplitting 的詳細資訊，請參閱 Rolldown 文件：Manual Code Splitting - Rolldown。

build() 丟擲 BundleError ​

此更改僅影響 JS API 使用者。

build() 現在丟擲 BundleError，而不是外掛中丟擲的原始錯誤。BundleError 的型別定義為 Error & { errors?: RolldownError[] }，它將各個錯誤包裝在一個 errors 陣列中。如果您需要獲取具體的單個錯誤，需要訪問 .errors。

js
try {
  await build()
} catch (e) {
  if (e.errors) {
    for (const error of e.errors) {
      console.log(error.code) // error code
    }
  }
}

模組型別支援和自動檢測 ​

此更改僅影響外掛作者。

Rolldown 對 模組型別 (Module types) 提供了實驗性支援，類似於 esbuild 的 loader 選項。因此，Rolldown 會根據解析出的 ID 副檔名自動設定模組型別。如果您在 load 或 transform 鉤子中將內容轉換為 JavaScript，您可能需要向返回值新增 moduleType: 'js'。

js
const plugin = {
  name: 'txt-loader',
  load(id) {
    if (id.endsWith('.txt')) {
      const content = fs.readFile(id, 'utf-8')
      return {
        code: `export default ${JSON.stringify(content)}`,
        moduleType: 'js', 
      }
    }
  },
}

以下選項已棄用，將來會被移除：

  • build.rollupOptions：更名為 build.rolldownOptions
  • worker.rollupOptions：更名為 worker.rolldownOptions
  • build.commonjsOptions：現已無效 (no-op)
  • build.dynamicImportVarsOptions.warnOnError：現已無效 (no-op)
  • resolve.alias[].customResolver：改為使用帶有 resolveId 鉤子且設定 enforce: 'pre' 的自定義外掛

移除了已棄用的功能 NRV ​

  • 不再支援將 URL 傳遞給 import.meta.hot.accept。請改為傳遞 id。（#21382）

進階 ​

預計這些破壞性更改只會影響少數用例

  • Extglobs 尚不支援（rolldown-vite#365）
  • TypeScript 遺留名稱空間（legacy namespace）僅部分支援。有關詳細資訊，請參閱 Oxc Transformer 相關文件。
  • define 不共享物件的引用：當您將物件作為值傳遞給 define 時，每個變數都將擁有該物件的獨立副本。有關詳細資訊，請參閱 Oxc Transformer 相關文件。
  • bundle 物件變更（bundle 是傳遞給 generateBundle / writeBundle 鉤子的物件，也是 build 函式返回的物件）
    • 不支援賦值給 bundle[foo]。Rollup 也不建議這樣做。請改為使用 this.emitFile()。
    • 引用在鉤子之間不共享（rolldown-vite#410）
    • structuredClone(bundle) 會報錯 DataCloneError: #<Object> could not be cloned。此操作不再支援。請使用 structuredClone({ ...bundle }) 進行克隆。（rolldown-vite#128）
  • Rollup 中的所有並行鉤子現在都作為順序鉤子執行。有關詳細資訊，請參閱 Rolldown 文件。
  • "use strict"; 有時不會被注入。有關詳細資訊，請參閱 Rolldown 文件。
  • 不支援透過 plugin-legacy 轉換為 ES5 及以下版本（rolldown-vite#452）
  • 向 build.target 選項傳遞同一個瀏覽器的多個版本現在會報錯：esbuild 會選擇該瀏覽器的最新版本，這很可能不是您的本意。
  • Rolldown 不支援：以下功能不受 Rolldown 支援，因此 Vite 也不再支援。
  • parseAst / parseAstAsync 函式現已被棄用，取而代之的是功能更強的 parseSync / parse 函式。

從 v6 遷移 ​

請先檢視 Vite v7 文件中的 從 v6 遷移指南，瞭解將應用移植到 Vite 7 所需的更改，然後再繼續進行此頁面上的更改。

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