Vite
ViteConf Logo

攜手共建

ViteConf 2025

觀看回放

環境 API ​

候選釋出版本 (Release Candidate)

環境 API 目前處於候選釋出階段。我們將在主要版本之間保持 API 的穩定性，以便生態系統能夠進行實驗和構建。但請注意，某些特定 API 仍被視為實驗性的。

一旦下游專案有時間試驗這些新功能並完成驗證，我們計劃在未來的主要版本中穩定這些新 API（可能會有破壞性變更）。

資源

請與我們分享您的反饋。

環境的正式化 ​

Vite 6 將“環境 (Environments)”的概念正式化。在 Vite 5 之前，存在兩個隱式環境（client 和可選的 ssr）。新的環境 API 允許使用者和框架作者建立任意數量的環境，以對映其應用在生產環境中的工作方式。這一新功能需要大規模的內部重構，但我們投入了大量精力來確保向後相容性。Vite 6 的首要目標是儘可能順利地將生態系統遷移到新版本，並延遲 API 的採用，直到足夠的使用者完成遷移，以及框架和外掛作者驗證了新設計。

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

對於簡單的 SPA/MPA，配置中不會暴露任何關於環境的新 API。在內部，Vite 會將選項應用於 client 環境，但在配置 Vite 時無需瞭解這一概念。Vite 5 的配置和行為在此處應能無縫工作。

當我們轉向典型的服務端渲染 (SSR) 應用時，我們將擁有兩個環境：

  • client：在瀏覽器中執行應用。
  • ssr：在 Node（或其他伺服器執行時）中執行應用，在傳送給瀏覽器之前渲染頁面。

在開發過程中，Vite 在與 Vite 開發伺服器相同的 Node 程序中執行伺服器程式碼，從而非常接近生產環境。然而，伺服器也可以在其他 JS 執行時中執行，例如具有不同約束的 Cloudflare 的 workerd。現代應用可能還會執行在超過兩個以上的環境中，例如瀏覽器、Node 伺服器和邊緣 (edge) 伺服器。Vite 5 無法恰當地表示這些環境。

Vite 6 允許使用者在構建和開發過程中配置其應用，以對映其所有環境。在開發階段，現在可以使用單個 Vite 開發伺服器同時在多個不同環境中執行程式碼。應用原始碼仍然由 Vite 開發伺服器進行轉換。在共享的 HTTP 伺服器、中介軟體、已解析的配置和外掛管道之上，Vite 開發伺服器現在擁有了一組獨立的環境。每個環境都配置為儘可能匹配生產環境，並連線到一個程式碼執行的開發執行時（例如，對於 workerd，伺服器程式碼現在可以在本地執行在 miniflare 中）。在客戶端，瀏覽器匯入並執行程式碼。在其他環境中，模組執行器 (module runner) 會獲取並評估轉換後的程式碼。

Vite Environments

環境配置 ​

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

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

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

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

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

當未顯式配置時，環境將繼承配置的頂層選項（例如，新的 server 和 edge 環境將繼承 build.sourcemap: false 選項）。少數幾個頂層選項（如 optimizeDeps）僅適用於 client 環境，因為當它們作為伺服器環境的預設選項時工作效果不佳。這些選項在參考文件中帶有 非繼承 徽章。client 環境也可以透過 environments.client 顯式配置，但我們建議使用頂層選項進行配置，以便在新增新環境時保持客戶端配置不變。

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

ts
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。

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

請注意，一旦環境 API 穩定，ssr 頂層屬性將被棄用。該選項的角色與 environments 相同，但僅針對預設的 ssr 環境，且僅允許配置少量選項。

自定義環境例項 ​

底層配置 API 可供使用，以便執行時提供者能夠為其執行時提供具有適當預設值的環境。這些環境也可以在開發過程中生成其他程序或執行緒，以在更接近生產環境的執行時中執行模組。

例如，Cloudflare Vite 外掛使用環境 API 在開發期間在 Cloudflare Workers 執行時 (workerd) 中執行程式碼。

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

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

向後相容性 ​

當前的 Vite 伺服器 API 尚未被棄用，並且與 Vite 5 向後相容。

server.moduleGraph 返回客戶端和 SSR 模組圖的混合檢視。其所有方法都將返回向後相容的混合模組節點。傳遞給 handleHotUpdate 的模組節點也使用相同的方案。

我們目前不建議切換到環境 API。我們的目標是在更多使用者群採用 Vite 6 之後，這樣外掛就不需要維護兩個版本。請檢視未來的破壞性變更部分，獲取有關未來棄用和升級路徑的資訊。

目標使用者 ​

本指南為終端使用者提供了關於環境的基本概念。

外掛作者可以使用更一致的 API 來與當前環境配置進行互動。如果您是在 Vite 之上進行構建，環境 API 外掛指南描述了支援多個自定義環境的擴充套件外掛 API 使用方式。

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

對於執行時提供者，環境 API 執行時指南解釋瞭如何提供自定義環境供框架和使用者使用。

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