環境 API

實驗性

環境 API 為實驗性功能。我們將在 Vite 6 期間保持 API 的穩定性，以便生態系統可以嘗試並在其基礎上進行建構。我們計劃在 Vite 7 中穩定這些新 API，並可能進行重大變更。

資源

回饋討論，我們正在收集關於新 API 的回饋意見。
環境 API PR，其中實作和審查了新的 API。

請與我們分享您的回饋意見。

形式化環境

Vite 6 正式定義了環境的概念。在 Vite 5 之前，有兩個隱含的環境（client 和可選的 ssr）。新的環境 API 允許使用者和框架作者根據需要在生產環境中建立多個環境，以對應應用程式的運作方式。這項新功能需要進行大規模的內部重構，但在向後相容性方面投入了大量精力。Vite 6 的最初目標是盡可能順利地將生態系統遷移到新的主要版本，將這些新的實驗性 API 的採用推遲到足夠多的使用者遷移並且框架和外掛作者驗證了新設計之後。

縮小建置與開發之間的差距

對於簡單的 SPA/MPA，沒有關於環境的新 API 會暴露在配置中。在內部，Vite 會將選項套用到 client 環境，但在配置 Vite 時，無需了解這個概念。Vite 5 的配置和行為在此應能無縫運作。

當我們遷移到典型的伺服器端渲染 (SSR) 應用程式時，我們將有兩個環境

client：在瀏覽器中執行應用程式。
server：在 node（或其他伺服器執行時）中執行應用程式，在將頁面傳送到瀏覽器之前進行渲染。

在開發中，Vite 在與 Vite 開發伺服器相同的 Node 處理程序中執行伺服器程式碼，使其與生產環境非常接近。然而，伺服器也可能在其他 JS 執行時中執行，例如 Cloudflare 的 workerd，它們具有不同的限制。現代應用程式也可能在兩個以上的環境中執行，例如瀏覽器、node 伺服器和邊緣伺服器。Vite 5 無法正確地表示這些環境。

Vite 6 允許使用者在建置和開發期間配置其應用程式，以對應其所有環境。在開發期間，現在可以使用單個 Vite 開發伺服器同時在多個不同的環境中執行程式碼。應用程式原始程式碼仍然由 Vite 開發伺服器轉換。除了共用的 HTTP 伺服器、中介軟體、解析的配置和外掛管道之外，Vite 開發伺服器現在還有一組獨立的開發環境。每個環境都經過配置，以盡可能接近生產環境，並連接到執行程式碼的開發執行時 (對於 workerd，伺服器程式碼現在可以在本機的 miniflare 中執行)。在用戶端中，瀏覽器匯入並執行程式碼。在其他環境中，模組執行器會擷取並評估轉換後的程式碼。

Vite Environments

環境配置

對於 SPA/MPA，配置看起來會與 Vite 5 相似。在內部，這些選項用於配置 client 環境。

export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})

這很重要，因為我們希望保持 Vite 的易用性，並避免在需要之前暴露新的概念。

如果應用程式由多個環境組成，則可以使用 environments 配置選項明確配置這些環境。

export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}

在未明確記錄時，環境會繼承已配置的頂層配置選項（例如，新的 server 和 edge 環境將繼承 build.sourcemap: false 選項）。少數頂層選項（例如 optimizeDeps）僅適用於 client 環境，因為它們在作為伺服器環境的預設值套用時效果不佳。也可以透過 environments.client 明確配置 client 環境，但我們建議使用頂層選項進行配置，以便在新增環境時，用戶端配置保持不變。

EnvironmentOptions 介面公開所有每個環境的選項。有些環境選項同時適用於 build 和 dev，例如 resolve。還有適用於開發和建置特定選項的 DevEnvironmentOptions 和 BuildEnvironmentOptions（例如 dev.warmup 或 build.outDir）。某些選項（例如 optimizeDeps）僅適用於開發，但為了向後相容性，保留為頂層選項，而不是巢狀於 dev 中。

interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}

UserConfig 介面繼承自 EnvironmentOptions 介面，允許配置用戶端和透過 environments 選項配置的其他環境的預設值。在開發期間，client 和名為 ssr 的伺服器環境始終存在。這樣可以向後相容於 server.ssrLoadModule(url) 和 server.moduleGraph。在建置期間，client 環境始終存在，而 ssr 環境僅在明確配置時才存在（使用 environments.ssr 或為了向後相容性使用 build.ssr）。應用程式不需要為其 SSR 環境使用 ssr 名稱，例如，它可以將其命名為 server。

interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}

請注意，一旦環境 API 穩定下來，ssr 頂層屬性將會被棄用。此選項與 environments 的作用相同，但適用於預設的 ssr 環境，並且僅允許配置一小組選項。

自訂環境實例

提供了低層級的配置 API，以便執行時供應商可以為其執行時提供具有適當預設值的環境。這些環境也可以衍生其他程序或執行緒，以便在開發期間在更接近生產環境的執行時中執行模組。

import { customEnvironment } from 'vite-environment-provider'

export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}

向後相容性

目前的 Vite 伺服器 API 尚未棄用，並且與 Vite 5 向後相容。新的環境 API 為實驗性功能。

server.moduleGraph 會傳回用戶端和 ssr 模組圖的混合檢視。向後相容的混合模組節點將從其所有方法傳回。相同的配置方案用於傳遞給 handleHotUpdate 的模組節點。

我們不建議您現在切換到環境 API。我們的目標是在外掛不需要維護兩個版本之前，讓大部分使用者採用 Vite 6。請查看未來的重大變更章節，以取得有關未來棄用和升級路徑的資訊

目標使用者

本指南提供了有關最終使用者環境的基本概念。

外掛作者可以使用更一致的 API 來與目前的環境配置互動。如果您正在 Vite 的基礎上進行建構，則環境 API 外掛指南說明了可用於支援多個自訂環境的擴充外掛 API 的方式。

框架可以決定在不同的層級公開環境。如果您是框架作者，請繼續閱讀環境 API 框架指南，以了解環境 API 的程式設計面。

對於執行時供應商，環境 API 執行時指南說明如何提供可供框架和使用者使用的自訂環境。

環境 API ​

形式化環境 ​

縮小建置與開發之間的差距 ​

環境配置 ​

自訂環境實例 ​

向後相容性 ​

目標使用者 ​