從 v5 遷移

環境 API

作為新的實驗性環境 API的一部分，需要進行大規模的內部重構。Vite 6 致力於避免重大變更，以確保大多數專案可以快速升級到新的主要版本。我們將等到大部分生態系統都轉移到新的 API 後，才會開始建議使用它們。可能會有一些邊緣案例，但這些案例只會影響框架和工具的底層使用。我們已與生態系統中的維護者合作，在發布之前緩解這些差異。如果您發現回歸，請開啟一個 issue。

由於 Vite 實作中的變更，一些內部 API 已被移除。如果您依賴其中一個 API，請建立一個功能請求。

Vite 執行環境 API

實驗性的 Vite 執行環境 API 演變為模組執行器 API，作為新的實驗性環境 API的一部分，在 Vite 6 中發布。由於該功能是實驗性的，因此移除 Vite 5.1 中引入的先前 API 並非重大變更，但使用者需要更新其用法為模組執行器的對等項目，作為遷移到 Vite 6 的一部分。

一般變更

resolve.conditions 的預設值

此變更不會影響未配置 resolve.conditions / ssr.resolve.conditions / ssr.resolve.externalConditions 的使用者。

在 Vite 5 中，resolve.conditions 的預設值為 []，並且在內部添加了一些條件。ssr.resolve.conditions 的預設值為 resolve.conditions 的值。

從 Vite 6 開始，一些條件不再在內部添加，需要包含在配置值中。不再在內部添加的條件為

• resolve.conditions 為 ['module', 'browser', 'development|production']
• ssr.resolve.conditions 為 ['module', 'node', 'development|production']

這些選項的預設值已更新為相應的值，並且 ssr.resolve.conditions 不再使用 resolve.conditions 作為預設值。請注意，development|production 是一個特殊變數，會根據 process.env.NODE_ENV 的值替換為 production 或 development。這些預設值從 vite 匯出為 defaultClientConditions 和 defaultServerConditions。

如果您為 resolve.conditions 或 ssr.resolve.conditions 指定了自訂值，則需要更新它以包含新的條件。例如，如果您之前為 resolve.conditions 指定了 ['custom']，則需要改為指定 ['custom', ...defaultClientConditions]。

JSON 字串化

在 Vite 5 中，當設定json.stringify: true 時，json.namedExports 會被停用。

從 Vite 6 開始，即使設定了 json.stringify: true，json.namedExports 也不會被停用，並且會尊重該值。如果您希望實現先前的行為，則可以設定 json.namedExports: false。

Vite 6 還為 json.stringify 引入了一個新的預設值，即 'auto'，它只會字串化大型 JSON 檔案。若要停用此行為，請設定 json.stringify: false。

擴充對 HTML 元素中資源參考的支援

在 Vite 5 中，只有少數受支援的 HTML 元素可以參考將由 Vite 處理和綁定的資源，例如 <link href>、<img src> 等。

Vite 6 將支援擴展到更多 HTML 元素。完整清單可以在HTML 功能文件中找到。

若要選擇退出在某些元素上進行 HTML 處理，您可以在元素上添加 vite-ignore 屬性。

postcss-load-config

postcss-load-config 已從 v4 更新到 v6。現在需要 tsx 或 jiti 來載入 TypeScript postcss 設定檔，而不是 ts-node。現在還需要 yaml 來載入 YAML postcss 設定檔。

Sass 現在預設使用現代 API

在 Vite 5 中，預設情況下 Sass 使用舊版 API。Vite 5.4 添加了對現代 API 的支援。

從 Vite 6 開始，預設情況下 Sass 使用現代 API。如果您仍希望使用舊版 API，則可以設定 css.preprocessorOptions.sass.api: 'legacy' / css.preprocessorOptions.scss.api: 'legacy'。但請注意，舊版 API 支援將在 Vite 7 中移除。

若要遷移到現代 API，請參閱Sass 文件。

在函式庫模式中自訂 CSS 輸出檔名

在 Vite 5 中，函式庫模式中的 CSS 輸出檔名始終為 style.css，並且無法通過 Vite 設定輕鬆更改。

從 Vite 6 開始，預設檔名現在使用 package.json 中的 "name"，與 JS 輸出檔案類似。如果設定了具有字串的 build.lib.fileName，該值也將用於 CSS 輸出檔名。若要明確設定不同的 CSS 檔名，您可以使用新的 build.lib.cssFileName 來配置它。

若要遷移，如果您依賴 style.css 檔名，則應根據您的套件名稱更新對它的參考。例如

package.json

{
  "name": "my-lib",
  "exports": {
    "./style.css": "./dist/style.css"
    "./style.css": "./dist/my-lib.css"
  }
}

如果您希望像 Vite 5 中一樣堅持使用 style.css，則可以改為設定 build.lib.cssFileName: 'style'。

進階

還有其他重大變更，這些變更只會影響少數使用者。

• [#17922] fix(css)!: 移除 ssr dev 中的預設匯入

  • 對 CSS 檔案的預設匯入的支援在 Vite 4 中已棄用，並在 Vite 5 中移除，但在 SSR 開發模式中仍然無意中支援。現在已移除此支援。

• [#15637] fix!: build.cssMinify 的預設值設定為 SSR 的 'esbuild'

  • 現在即使對於 SSR 建置，也會預設啟用build.cssMinify。

• [#18070] feat!: 使用 WebSocket 繞過代理

  • 現在會為 WebSocket 升級請求呼叫 server.proxy[path].bypass，在這種情況下，res 參數將為 undefined。

• [#18209] refactor!: 將最低 terser 版本提升到 5.16.0

  • 對於 build.minify: 'terser'，最低支援的 terser 版本已從 5.4.0 提升到 5.16.0。

• [#18231] chore(deps): 將依賴項 @rollup/plugin-commonjs 更新到 v28

  • 現在 commonjsOptions.strictRequires 預設為 true（之前為 'auto'）。
    • 這可能會導致更大的套件大小，但會產生更具確定性的建置。
    • 如果您將 CommonJS 檔案指定為進入點，則可能需要其他步驟。請閱讀 commonjs 外掛文件以了解更多詳細資訊。

• [#18243] chore(deps)!: 將 fast-glob 遷移到 tinyglobby

  • 現在在 globs 中不再支援範圍大括號 ({01..03} ⇒ ['01', '02', '03']) 和遞增大括號 ({2..8..2} ⇒ ['2', '4', '6', '8'])。

• [#18395] feat(resolve)!: 允許移除條件

  • 此 PR 不僅引入了上述提及的「resolve.conditions 的預設值」這項重大變更，也使得 resolve.mainFields 不再用於 SSR 中未外部化的依賴項。如果您先前使用 resolve.mainFields 並希望將其應用於 SSR 中未外部化的依賴項，可以使用 ssr.resolve.mainFields。

• [#18493] refactor!: 移除 fs.cachedChecks 選項

  • 由於在快取資料夾中寫入檔案並立即匯入時會出現邊緣情況，因此移除了這個選擇性的最佳化。

• [#18697] fix(deps)!: 更新依賴項 dotenv-expand 至 v12

  • 現在，在插值中使用的變數必須在插值之前宣告。更多詳細資訊，請參閱 dotenv-expand 的變更日誌。

• [#16471] feat: v6 - 環境 API

  • 對僅限 SSR 模組的更新不再觸發客戶端中的完整頁面重新載入。要恢復到先前的行為，可以使用自訂的 Vite 外掛程式。

    點擊展開範例

    import type { Plugin, EnvironmentModuleNode } from 'vite'
    
    function hmrReload(): Plugin {
      return {
        name: 'hmr-reload',
        enforce: 'post',
        hotUpdate: {
          order: 'post',
          handler({ modules, server, timestamp }) {
            if (this.environment.name !== 'ssr') return
    
            let hasSsrOnlyModules = false
    
            const invalidatedModules = new Set<EnvironmentModuleNode>()
            for (const mod of modules) {
              if (mod.id == null) continue
              const clientModule =
                server.environments.client.moduleGraph.getModuleById(mod.id)
              if (clientModule != null) continue
    
              this.environment.moduleGraph.invalidateModule(
                mod,
                invalidatedModules,
                timestamp,
                true,
              )
              hasSsrOnlyModules = true
            }
    
            if (hasSsrOnlyModules) {
              server.ws.send({ type: 'full-reload' })
              return []
            }
          },
        },
      }
    }

從 v4 遷移

請先查看 Vite v5 文件中的 從 v4 遷移指南，了解將您的應用程式移植到 Vite 5 所需的變更，然後再繼續進行此頁面上的變更。