Vite 環境變數管理：如何優雅地切換開發與生產環境？

在前端開發中，我們經常需要根據不同環境，例如：開發、測試、生產，使用不同的 API 或金鑰。在 Vite 專案中，mode 參數與 .env 檔案是管理這些行為的核心。

認識 Vite 的預設模式 (Mode)

在 vite.config.js 配置中，mode 參數表示當前的建構模式，它決定了應用程式的運行環境和行為。可以透過 mode 參數判斷目前的執行環境。

• development：開發模式，執行 vite 或 vite dev 時觸發。
• production：生產模式，執行 vite build 時觸發。

export default defineConfig(({ mode }) => {
  // 透過 mode 可以得知目前是 'development' 還是 'production'
  console.log(mode);

  return {
    // 相關配置...
  };
});

環境檔 .env 的建立與載入順序

Vite 會自動根據目前的模式載入對應的環境檔，建議將這些檔案放在專案的 根目錄 下。

檔案	載入時機與說明
.env	所有環境都會優先載入，存放共用變數。
.env.development	npm run dev 時使用。
.env.production	npm run build 時使用。
.env.[mode]	載入特定的環境變數時使用

命名規範：VITE_ 前綴

為了防止環境變數意外洩露給客戶端，Vite 規定只有以 VITE_ 開頭的變數才會被暴露給您的程式碼。

VITE_API_URL = https://api.example.com
VITE_APP_NAME = MyApp

進階技巧：在配置中使用 loadEnv

有時候我們需要在 vite.config.js 內部就先讀取到環境變數，例如：根據環境設定不同的 Proxy 代理，這時就需要用到 loadEnv。

import { defineConfing, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  // 手動載入環境變數
  const env = loadEnv(mode, process.cwd(), "");

  console.log(env);

  return {
    // 您的配置...
  };
});

loadEnv 參數詳解

• mode：Vite 目前的執行模式。它決定了要去找哪個 .env.[mode] 檔案。
• process.cwd()：代表目前專案的根目錄路徑，告訴 Vite 到哪裡尋找環境檔。
• '' (前綴字)：這是過濾條件。預設 Vite 只會加載 VITE_ 開頭的變數。如果您傳入空字串 ''，則會載入該環境檔中的所有變數。

常見問題：解決 ESLint 報錯

在 vite.config.js 中使用 process.cwd() 時，可能會遇到 no-undef 的 ESLint 警告。您可以選擇以下任一方式解決：

• 該行程式碼上方加上 // eslint-disable-next-line no-undef。
• 該檔案的第一行加上 /* eslint-disable no-undef */。
• 該檔案的第一行加上 /* global process */。
• 在 ESLint 配置中設定環境：

  {
    env: {
      node: true;
    }
  }

結語

精確管理環境變數是確保應用程式安全與穩定的關鍵。透過 Vite 內建的 mode 機制搭配 .env 檔案，您可以輕鬆實現「一套程式碼，多環境運行」。別忘了，敏感資料（如私鑰）千萬不要加上 VITE_ 前綴，以確保它們只留在伺服器端！