Vite 環境變數管理與部署優化 提升前端開發流程與 CI CD 穩定性

如何在 Vite 中正確管理環境變數？

Vite 環境變數教學 的核心在於理解 ESM 模式下的配置邏輯。高品質的 前端環境配置 主要分為三種實作方式：1. .env 檔案管理：利用 VITE_ 前綴規範（如 VITE_API_URL）確保變數能透過 import.meta.env 被前端存取；2. loadEnv 函式：在 vite.config.js 中動態讀取系統變數，適合複雜的 CI/CD 環境管理；3. ESBuild Define：將變數定義為全域常數，強化編譯期替換。透過這套 多環境部署策略，開發者能確保 Vite 專案部署 在開發 (dev)、測試 (staging) 與生產 (prod) 環境間無縫切換，並利用 Vite TypeScript 類型定義避免開發時的語法錯誤。

在現代前端開發中，Vite 作為一個高效的構建工具，其環境變數的妥善管理對於專案的穩定運行和多環境部署至關重要。無論是前端應用程式在開發、測試，還是生產環境間的無縫切換，Vite 環境變數都提供了不可或缺的靈活性與控制力。

本文將深入解析 Vite 環境變數的設定與應用，特別關注它們如何簡化前端開發與 CI/CD 流程，並確保多環境部署的穩定與彈性。

Vite 系統環境變數設定

Vite 是下一代高效的前端模組打包工具，背後直接使用 ESM 所以可以達到快速即時的開發體驗，在 JavaScript 生態系中提供極佳開發體驗。但也由於是 ESM 的關係，處理環境變數上的設定有些許不同。

尤其是在 CI/CD 流程中，自動化部署時通常會透過 pipeline 設定環境變數，但這樣的設定就和 Vite 本身直接支援的方式略有落差。

Vite 環境變數的設定主要有兩種做法：使用 Vite 內建機制或是直接讀取 pipeline 上的系統環境變數。

Vite 內建的環境變數處理方式，參考下面的連結，關鍵就是依照環境多寫一份 .env 檔案，像是 .env.production、.env.staging，並在執行時搭配 --mode staging。環境變數中的 Key 需要用 VITE 開頭（例如 VITE_SOME_KEY），最後就可以用特殊的全域變數使用 import.meta.env.VITE_SOME_KEY 來使用。

https://vitejs.dev/guide/env-and-mode.html#node-env-and-modes

透過 Vite 內建函式讀取系統的環境變數，並透過 ESM define 成全域變數，這個方式就不用額外再定義環境檔

https://vitejs.dev/config/#using-environment-variables-in-config

1
2
3
4
5
6
7
8
9
10
11
12
13

import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ command, mode }) => {
  // Load env file based on `mode` in the current working directory.
  // Set the third parameter to '' to load all env regardless of the `VITE_` prefix.
  const env = loadEnv(mode, process.cwd(), "");
  return {
    // vite config
    define: {
      __APP_ENV__: JSON.stringify(env.APP_ENV),
    },
  };
});

但因為是透過 ESBuild 的 define 成全域變數關係，所以如果是使用 TypeScript 需要額外進行底下設定，才不會出現錯誤警告。

https://vitejs.dev/config/shared-options.html#define

1
2

// vite-env.d.ts
declare const __APP_VERSION__: string;

總而言之，Vite 環境變數是前端開發中不可或缺的配置管理工具。透過有效地利用 Vite 的內建機制或與 CI/CD 流程的整合，開發者能夠確保多環境部署的順暢與安全。

這不僅簡化前端開發的複雜性，提升程式碼品質，更能讓前端工程師將重心放在更具創新性的工作上。掌握 Vite 環境變數的設定與應用，是現代軟體開發中實現高效與靈活的關鍵一環。

FAQ：Vite 環境變數管理常見問題

Q1：為什麼 Vite 要求環境變數必須以 VITE_ 開頭？

A：這是一項高品質的「安全防護機制」。Vite 專案中可能存在許多敏感的系統環境變數（如資料庫密碼或 API Key）。為了防止這些秘密無意中被打包進前端瀏覽器端程式碼，Vite 預設僅會暴露以 VITE_ 開頭的變數到 import.meta.env 中。

Q2：在 CI/CD 流程中，如何將 Pipeline 上的變數注入 Vite？

A：高品質的 CI/CD 環境管理 實務是使用 loadEnv 函式。在 vite.config.js 中，您可以呼叫 loadEnv(mode, process.cwd(), '')。第三個參數設為空字串，即可讓 Vite 讀取到系統層級的所有環境變數，並透過 define 選項將它們映射到前端可以存取的變數名稱上。

Q3：如何解決 TypeScript 找不到 import.meta.env 屬性的錯誤？

A：您需要在專案中建立或修改 src/vite-env.d.ts 檔案。透過擴展 ImportMetaEnv 介面，您可以為自定義的環境變數提供型別聲明（如：readonly VITE_API_BASE_URL: string）。這能讓您在開發時獲得自動完成提示，並確保 Vite TypeScript 編譯期的安全性。

• ← 上一篇
• 下一篇 →