環境變數與模式

環境變數

Vite 在特殊的 **import.meta.env** 物件上公開環境變數，這些變數會在構建時被靜態替換。某些內建變數在所有情況下都可用

**import.meta.env.MODE**：{string} 應用程式正在執行的模式。
**import.meta.env.BASE_URL**：{string} 應用程式正在提供的基準網址。這由base 配置選項決定。
**import.meta.env.PROD**：{boolean} 應用程式是否在生產環境中執行（使用 NODE_ENV='production' 執行開發伺服器或執行使用 NODE_ENV='production' 構建的應用程式）。
**import.meta.env.DEV**：{boolean} 應用程式是否在開發環境中執行（永遠與 import.meta.env.PROD 相反）
**import.meta.env.SSR**：{boolean} 應用程式是否在伺服器中執行。

`.env` 檔案

Vite 使用 dotenv 從您的環境目錄中的以下檔案載入其他環境變數

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

環境載入優先順序

特定模式的環境檔案（例如 .env.production）會比通用檔案（例如 .env）具有更高的優先順序。

除了特定模式的 .env.[mode] 檔案之外，Vite 還會始終載入 .env 和 .env.local。在特定模式檔案中宣告的變數會優先於通用檔案中的變數，但僅在 .env 或 .env.local 中定義的變數仍然可在環境中使用。

此外，Vite 執行時已存在的環境變數具有最高優先順序，並且不會被 .env 檔案覆寫。例如，當執行 VITE_SOME_KEY=123 vite build 時。

.env 檔案會在 Vite 開始時載入。在變更後重新啟動伺服器。

載入的環境變數也會透過 import.meta.env 作為字串公開給您的客戶端原始程式碼。

為了防止意外洩露環境變數到客戶端，只有以 VITE_ 為前綴的變數才會公開給您的 Vite 處理的程式碼。例如，針對以下環境變數

.env

VITE_SOME_KEY=123
DB_PASSWORD=foobar

只有 VITE_SOME_KEY 會作為 import.meta.env.VITE_SOME_KEY 公開給您的客戶端原始程式碼，但 DB_PASSWORD 不會。

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

環境解析

如上所示，VITE_SOME_KEY 是一個數字，但在解析時會傳回字串。布林環境變數也會發生同樣的情況。請務必在程式碼中使用時轉換為所需的類型。

此外，Vite 使用 dotenv-expand 來擴充環境檔案中寫入的變數。若要深入瞭解語法，請查看他們的檔案。

請注意，如果您想要在環境值中使用 $，您必須使用 \ 逸出它。

.env

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

如果您想要自訂環境變數前綴，請參閱 envPrefix 選項。

安全性注意事項

.env.*.local 檔案僅限本機使用，並且可能包含敏感變數。您應該將 *.local 新增至您的 .gitignore，以避免將其簽入 git。
由於任何公開給您的 Vite 原始程式碼的變數都會最終出現在您的客戶端套件中，因此 VITE_* 變數 *不應* 包含任何敏感資訊。

TypeScript 的 IntelliSense

預設情況下，Vite 在 vite/client.d.ts 中提供 import.meta.env 的類型定義。雖然您可以在 .env.[mode] 檔案中定義更多自訂環境變數，但您可能希望為以 VITE_ 為前綴的使用者定義環境變數取得 TypeScript IntelliSense。

若要達成此目的，您可以在 src 目錄中建立 vite-env.d.ts，然後像這樣擴充 ImportMetaEnv

vite-env.d.ts

typescript

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

如果您的程式碼依賴瀏覽器環境（例如 DOM 和 WebWorker）中的類型，您可以更新 tsconfig.json 中的 lib 欄位。

tsconfig.json

json

{
  "lib": ["WebWorker"]
}

匯入會中斷類型擴充

如果 ImportMetaEnv 擴充無法運作，請確保您的 vite-env.d.ts 中沒有任何 import 陳述式。如需更多資訊，請參閱 TypeScript 文件。

HTML 環境替換

Vite 也支援在 HTML 檔案中替換環境變數。import.meta.env 中的任何屬性都可以使用特殊的 %ENV_NAME% 語法在 HTML 檔案中使用

html

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

如果環境不存在於 import.meta.env 中，例如 %NON_EXISTENT%，它將被忽略且不會被取代，這與 JS 中的 import.meta.env.NON_EXISTENT 不同，後者會被取代為 undefined。

鑑於 Vite 被許多框架使用，它對複雜的替換（例如條件式）故意不作規範。Vite 可以使用現有的使用者端外掛或實作 transformIndexHtml 掛鉤的自訂外掛進行擴充。

模式

預設情況下，開發伺服器（dev 命令）在 development 模式下執行，而 build 命令在 production 模式下執行。

這表示當執行 vite build 時，如果存在 .env.production，它將從中載入環境變數

# .env.production
VITE_APP_TITLE=My App

在您的應用程式中，您可以使用 import.meta.env.VITE_APP_TITLE 呈現標題。

在某些情況下，您可能想要使用不同的模式執行 vite build，以呈現不同的標題。您可以透過傳遞 --mode 選項旗標來覆寫用於命令的預設模式。例如，如果您想要為暫存模式構建您的應用程式

bash

vite build --mode staging

並建立 .env.staging 檔案

# .env.staging
VITE_APP_TITLE=My App (staging)

由於 vite build 預設會執行生產構建，您也可以變更此設定並透過使用不同的模式和 .env 檔案配置來執行開發構建

# .env.testing
NODE_ENV=development

NODE_ENV 與模式

請務必注意，NODE_ENV (process.env.NODE_ENV) 和模式是兩個不同的概念。以下是不同的命令如何影響 NODE_ENV 和模式

命令	NODE_ENV	模式
`vite build`	`"production"`	`"production"`
`vite build --mode development`	`"production"`	`"development"`
`NODE_ENV=development vite build`	`"development"`	`"production"`
`NODE_ENV=development vite build --mode development`	`"development"`	`"development"`

NODE_ENV 和模式的不同值也會反映在其對應的 import.meta.env 屬性上

命令	`import.meta.env.PROD`	`import.meta.env.DEV`
`NODE_ENV=production`	`true`	`false`
`NODE_ENV=development`	`false`	`true`
`NODE_ENV=other`	`false`	`true`

命令	`import.meta.env.MODE`
`--mode production`	`"production"`
`--mode development`	`"development"`
`--mode staging`	`"staging"`

.env 檔案中的 NODE_ENV

NODE_ENV=... 可以在命令中設定，也可以在您的 .env 檔案中設定。如果 NODE_ENV 在 .env.[mode] 檔案中指定，則可以使用模式來控制其值。但是，NODE_ENV 和模式仍然是兩個不同的概念。

在命令中使用 NODE_ENV=... 的主要好處是，它允許 Vite 提前偵測該值。它也允許您在 Vite 設定中讀取 process.env.NODE_ENV，因為 Vite 只能在評估設定後載入環境檔案。

環境變數與模式 ​

環境變數 ​

.env 檔案 ​

TypeScript 的 IntelliSense ​

HTML 環境替換 ​

模式 ​

NODE_ENV 與模式 ​