Vite 環(huán)境變量和模式

環(huán)境變量

Vite 在一個(gè)特殊的 ?import.meta.env? 對(duì)象上暴露環(huán)境變量。這里有一些在所有情況下都可以使用的內(nèi)建變量：

• ?import.meta.env.MODE?: {string} 應(yīng)用運(yùn)行的模式。
• ?import.meta.env.BASE_URL?: {string} 部署應(yīng)用時(shí)的基本 URL。他由?base? 配置項(xiàng)決定。
• ?import.meta.env.PROD?: {boolean} 應(yīng)用是否運(yùn)行在生產(chǎn)環(huán)境。
• ?import.meta.env.DEV?: {boolean} 應(yīng)用是否運(yùn)行在開發(fā)環(huán)境 (永遠(yuǎn)與 ?import.meta.env.PROD?相反)。

生產(chǎn)環(huán)境替換

在生產(chǎn)環(huán)境中，這些環(huán)境變量會(huì)在構(gòu)建時(shí)被靜態(tài)替換，因此，在引用它們時(shí)請(qǐng)使用完全靜態(tài)的字符串。動(dòng)態(tài)的 key 將無(wú)法生效。例如，動(dòng)態(tài) key 取值 ?import.meta.env[key]? 是無(wú)效的。

它還將替換出現(xiàn)在 JavaScript 和 Vue 模板中的字符串。這本應(yīng)是非常少見(jiàn)的，但也可能是不小心為之的。在這種情況下你可能會(huì)看到類似 ?Missing Semicolon? 或 ?Unexpected token? 等錯(cuò)誤，例如當(dāng) ?"process.env.NODE_ENV"? 被替換為 ?"development": ""?。有一些方法可以避免這個(gè)問(wèn)題：

• 對(duì)于 JavaScript 字符串，你可以使用 unicode 零寬度空格 ?\u200b? (一個(gè)看不見(jiàn)的分隔符)來(lái)分割這個(gè)字符串，例如： ?'import.meta\u200b.env.MODE'?。
• 對(duì)于 Vue 模板或其他編譯到 JavaScript 字符串的 HTML，你可以使用 <wbr> 標(biāo)簽，例如：?import.meta.<wbr>env.MODE?。

.env文件

Vite 使用 dotenv 從你的 環(huán)境目錄 中的下列文件加載額外的環(huán)境變量：

.env                # 所有情況下都會(huì)加載
.env.local          # 所有情況下都會(huì)加載，但會(huì)被 git 忽略
.env.[mode]         # 只在指定模式下加載
.env.[mode].local   # 只在指定模式下加載，但會(huì)被 git 忽略

加載的環(huán)境變量也會(huì)通過(guò) ?import.meta.env? 暴露給客戶端源碼。

為了防止意外地將一些環(huán)境變量泄漏到客戶端，只有以 ?VITE_? 為前綴的變量才會(huì)暴露給經(jīng)過(guò) vite 處理的代碼。例如下面這個(gè)文件中：

DB_PASSWORD=foobar
VITE_SOME_KEY=123

只有 VITE_SOME_KEY 會(huì)被暴露為 import.meta.env.VITE_SOME_KEY 提供給客戶端源碼，而 DB_PASSWORD 則不會(huì)。

注意事項(xiàng)：

• ?.env.*.local? 文件應(yīng)是本地的，可以包含敏感變量。你應(yīng)該將 ?.local? 添加到你的 ?.gitignore? 中，以避免它們被 git 檢入。
• 由于任何暴露給 Vite 源碼的變量最終都將出現(xiàn)在客戶端包中，?VITE_*? 變量應(yīng)該不包含任何敏感信息。

TypeScript的智能提示

默認(rèn)情況下，Vite 在 vite/client.d.ts 中為 ?import.meta.env? 提供了類型定義。隨著在 ?.env[mode]? 文件中自定義了越來(lái)越多的環(huán)境變量，你可能想要在代碼中獲取這些以 ?VITE_? 為前綴的用戶自定義環(huán)境變量的 TypeScript 智能提示。

要想做到這一點(diǎn)，你可以在 ?src? 目錄下創(chuàng)建一個(gè) ?env.d.ts? 文件，接著按下面這樣增加 ?ImportMetaEnv? 的定義：

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

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // 更多環(huán)境變量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

模式

默認(rèn)情況下，開發(fā)服務(wù)器 (?dev命令) 運(yùn)行在 ?development(開發(fā)) 模式，而 ?build以及 ?serve命令則運(yùn)行在 ?production? (生產(chǎn)) 模式。

這意味著當(dāng)執(zhí)行 ?vite build? 時(shí)，它會(huì)自動(dòng)加載 ?.env.production? 中可能存在的環(huán)境變量：

# .env.production
VITE_APP_TITLE=My App

在你的應(yīng)用中，你可以使用 ?import.meta.env.VITE_APP_TITLE? 渲染標(biāo)題。

然而，重要的是要理解 模式 是一個(gè)更廣泛的概念，而不僅僅是開發(fā)和生產(chǎn)。一個(gè)典型的例子是，你可能希望有一個(gè) “staging” (預(yù)發(fā)布|預(yù)上線) 模式，它應(yīng)該具有類似于生產(chǎn)的行為，但環(huán)境變量與生產(chǎn)環(huán)境略有不同。

你可以通過(guò)傳遞 ?--mode? 選項(xiàng)標(biāo)志來(lái)覆蓋命令使用的默認(rèn)模式。例如，如果你想為我們假設(shè)的 staging 模式構(gòu)建應(yīng)用：

vite build --mode staging

為了使應(yīng)用實(shí)現(xiàn)預(yù)期行為，我們還需要一個(gè) .env.staging 文件：

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

現(xiàn)在，你的 staging 應(yīng)用應(yīng)該具有類似于生產(chǎn)的行為，但顯示的標(biāo)題與生產(chǎn)環(huán)境不同。