建立 2026-09-16 更新 2026-09-16

環境變數與模式

不同環境（開發、測試、正式）常需要不同的設定值，例如 API 網址。Vite 透過 .env 系列檔案與「模式（mode）」的概念，讓這些設定與程式碼分離，也避免把機密資訊誤植入版本控制。

.env 系列檔案

Vite 使用 dotenv 讀取專案根目錄下的環境變數檔案，依載入優先順序：

檔名	用途
`.env`	所有模式都會載入的預設值
`.env.local`	所有模式都會載入，但不應提交到版本控制（通常存放個人機密設定）
`.env.[mode]`	只在指定模式（例如 `development`、`production`）載入
`.env.[mode].local`	只在指定模式載入，且不提交到版本控制

.local 結尾的檔案應加進 .gitignore（Vite 官方範本已預設排除），避免 API 金鑰等機密資訊外洩。

基於安全考量，Vite 只會把以 VITE_ 開頭的變數注入到前端可存取的 import.meta.env，其餘變數（例如資料庫密碼）即使寫在 .env 裡，也不會被打包進前端程式碼：

# .env
VITE_API_URL=https://api.example.com
DB_PASSWORD=super-secret   # 不會曝露給前端

console.log(import.meta.env.VITE_API_URL)
// https://api.example.com

console.log(import.meta.env.DB_PASSWORD)
// undefined

前端環境變數不是機密

即使加了 VITE_ 前綴、正確注入，這些值最終還是會被打包進瀏覽器能看到的 JavaScript 檔案。任何不希望使用者看到的機密（金鑰、密碼），都不應該放進 VITE_ 開頭的變數，而應該留在後端。

除了自訂的 VITE_ 變數，Vite 也提供幾個內建變數：

變數	說明
`import.meta.env.MODE`	目前執行模式（如 `development`、`production`）
`import.meta.env.PROD`	是否為正式環境的布林值
`import.meta.env.DEV`	是否為開發環境的布林值
`import.meta.env.BASE_URL`	部署時的基礎路徑，對應 `vite.config` 的 `base` 設定

模式預設由指令決定：vite（dev）預設是 development，vite build 預設是 production。可以用 --mode 參數覆寫，例如建立一個 staging 環境：

vite build --mode staging

搭配 .env.staging 檔案，就能在同一份程式碼中，依部署目標載入不同設定，不需要為每個環境維護不同分支或手動改程式碼。