Vue3+Vite環(huán)境變量與多環(huán)境配置詳解
概覽
在現(xiàn)代前端開發(fā)中，為不同的環(huán)境（如開發(fā)、測試、生產）配置不同的參數(shù)是基本需求。Vue3結合Vite構建工具提供了一套清晰的環(huán)境變量管理機制。本文將詳細介紹如何在Vue3+Vite項目中配置和使用環(huán)境變量。
1. 環(huán)境變量基礎
1.1 什么是 import.meta.env？
在Vite項目中，環(huán)境變量通過特殊的 import.meta.env 對象暴露給客戶端代碼。這些變量在開發(fā)階段全局可用，在構建時會被靜態(tài)替換，以便進行優(yōu)化（如tree-shaking）。
Vite內置了一些常用的環(huán)境變量：
- import.meta.env.MODE: 應用運行的模式（如 development、production）
- import.meta.env.BASE_URL: 部署應用時的基本URL，由vite配置中的base選項決定
- import.meta.env.PROD: 是否運行在生產環(huán)境（布爾值）
- import.meta.env.DEV: 是否運行在開發(fā)環(huán)境（布爾值，始終與PROD相反）
- import.meta.env.SSR: 是否運行在服務端渲染環(huán)境（布爾值）
1.2 環(huán)境變量的安全規(guī)則
Vite有一個重要的安全規(guī)則：只有以 VITE_ 為前綴的變量才會暴露給客戶端代碼。這是為了防止敏感信息（如數(shù)據庫密碼、API密鑰）意外泄漏到客戶端。
? 客戶端可訪問
VITE_API_BASE_URL=https://api.example.com
? 客戶端不可訪問
DB_PASSWORD=foobar SECRET_KEY=123456
如果需要自定義環(huán)境變量前綴，可以在vite.config.ts中配置：
export default defineConfig({
plugins: [vue()],
envPrefix: "APP_", // 自定義前綴
})2. 環(huán)境變量文件與多環(huán)境配置
2.1 環(huán)境文件結構與加載優(yōu)先級
Vite使用dotenv從環(huán)境目錄加載額外的環(huán)境變量，支持以下文件結構：
- .env - 所有情況下都會加載
- .env.local - 所有情況下都會加載，但會被git忽略
- .env.[mode] - 只在指定模式下加載
- .env.[mode].local - 只在指定模式下加載，但會被git忽略
環(huán)境加載優(yōu)先級：模式特定文件（如.env.[mode].local）> .env.[mode] > .env.local > .env。較早列出的文件具有更高優(yōu)先級，同名變量會被覆蓋。
2.2 配置多環(huán)境文件
下面是一個典型的多環(huán)境配置示例：
.env（全局默認配置）
所有環(huán)境共用配置
VITE_APP_TITLE=我的應用 VITE_API_TIMEOUT=5000
開發(fā)環(huán)境
.env.development（開發(fā)環(huán)境）
VITE_APP_TITLE=我的應用(開發(fā)版) VITE_API_BASE_URL=http://localhost:3000/api VITE_ENABLE_DEBUG=true
生產環(huán)境
.env.production（生產環(huán)境）
VITE_APP_TITLE=我的應用 VITE_API_BASE_URL=https://api.example.com VITE_ENABLE_DEBUG=false
預發(fā)布環(huán)境
.env.staging（預發(fā)布環(huán)境）
VITE_APP_TITLE=我的應用(預發(fā)布) VITE_API_BASE_URL=https://staging-api.example.com VITE_ENABLE_DEBUG=false
2.3 配置package.json腳本
在package.json中配置對應環(huán)境的啟動和構建命令：
{
"scripts": {
"dev": "vite --mode development",
"dev:test": "vite --mode test",
"dev:staging": "vite --mode staging",
"build": "vite build --mode production",
"build:test": "vite build --mode test",
"build:staging": "vite build --mode staging",
"preview": "vite preview"
}
}通過–mode參數(shù)指定模式，Vite會自動加載對應模式的環(huán)境變量文件。
3. 在代碼中使用環(huán)境變量
3.1 訪問環(huán)境變量
在Vue組件或JavaScript/TypeScript文件中，通過import.meta.env訪問環(huán)境變量：
// 獲取API基礎地址
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
// 環(huán)境判斷
if (import.meta.env.DEV) {
console.log('開發(fā)環(huán)境，啟用調試工具');
}
// 獲取當前模式
const currentMode = import.meta.env.MODE;
在Vue組件中的使用示例：
<template>
<div>
<h1>{{ appTitle }}</h1>
<p>API地址: {{ apiUrl }}</p>
<p>當前環(huán)境: {{ isDev ? '開發(fā)環(huán)境' : '生產環(huán)境' }}</p>
</div>
</template><script setup> const appTitle = import.meta.env.VITE_APP_TITLE; const apiUrl = import.meta.env.VITE_API_BASE_URL; const isDev = import.meta.env.DEV; </script>
3.2 在Vite配置中使用環(huán)境變量
在vite.config.js中，可以使用loadEnv函數(shù)手動加載環(huán)境變量：
import { defineConfig, loadEnv } from 'vite';
export default defineConfig(({ command, mode }) => {
// 加載環(huán)境變量
// 設置第三個參數(shù)為 '' 可加載所有環(huán)境變量（無論前綴）
const env = loadEnv(mode, process.cwd(), '');
return {
server: {
port: env.VITE_DEV_PORT ? Number(env.VITE_DEV_PORT) : 5173,
proxy: {
'/api': {
target: env.VITE_API_PROXY_TARGET,
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
},
},
},
build: {
outDir: `dist-${env.VITE_PROJECT_ID || 'app'}`,
},
define: {
__APP_VERSION__: JSON.stringify(env.VITE_VERSION || '1.0.0'),
},
};
});
4. TypeScript智能提示
為了在TypeScript中獲得環(huán)境變量的智能提示，需要在項目中添加類型定義。
創(chuàng)建src/vite-env.d.ts文件：
/// <reference types="vite/client" />
interface ImportMetaEnv {
// 內置變量
readonly MODE: string;
readonly BASE_URL: string;
readonly DEV: boolean;
readonly PROD: boolean;
readonly SSR: boolean;
// 自定義環(huán)境變量
readonly VITE_APP_TITLE: string;
readonly VITE_API_BASE_URL: string;
readonly VITE_ENABLE_DEBUG: string;
readonly VITE_API_TIMEOUT: string;
// 更多環(huán)境變量...
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
確保tsconfig.json中包含此類型定義文件：
{
“include”: [“src//*.ts", "src//*.d.ts”]
}5. 高級技巧與最佳實踐
5.1 自定義環(huán)境文件目錄
默認情況下，Vite在項目根目錄查找環(huán)境文件。可以通過envDir配置項指定自定義目錄：
//vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
envDir: path.resolve(__dirname, './env'), // 指定環(huán)境文件目錄
});5.2 運行時配置覆蓋
為了實現(xiàn)"一次構建，多處部署"，可以使用運行時配置覆蓋技術：
public/config.js
window.__APP_CONFIG__ = {
API_BASE_URL: "https://runtime-api.example.com",
APP_TITLE: "我的應用(運行時配置)",
UPLOAD_URL: "https://runtime-cdn.example.com"
};
在HTML中引入
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>My App</title>
<script src="/config.js"></script> <!-- 必須在應用腳本之前加載 -->
</head>
<body>
<div id="app"></div>
<script type="module" src="/src/main.js"></script>
</body>
</html>
統(tǒng)一配置封裝
const runtime = window.__APP_CONFIG__ || {};
export const APP_CONFIG = {
// API配置
API_BASE_URL: runtime.API_BASE_URL || import.meta.env.VITE_API_BASE_URL,
// 應用信息
APP_TITLE: runtime.APP_TITLE || import.meta.env.VITE_APP_TITLE,
// 環(huán)境信息
IS_DEV: import.meta.env.DEV,
IS_PROD: import.meta.env.PROD,
MODE: import.meta.env.MODE
};
5.3 環(huán)境變量驗證
創(chuàng)建環(huán)境變量驗證工具確保配置完整性：
export class EnvValidator {
static requiredVariables = [
'VITE_API_BASE_URL',
'VITE_APP_TITLE'
];
static validate() {
const missing = this.requiredVariables.filter(
key => !import.meta.env[key]
);
if (missing.length > 0) {
console.error('缺少必需的環(huán)境變量:', missing);
if (import.meta.env.DEV) {
alert(`缺少必需的環(huán)境變量: ${missing.join(', ')}`);
}
return false;
}
console.log('環(huán)境變量檢查通過');
return true;
}
}
// 應用啟動時驗證
EnvValidator.validate();
6. 安全注意事項
- 敏感信息保護：切勿將密碼、Token等敏感信息放在VITE_開頭的變量中。
- Git忽略配置：確保.env.local和*.local文件已添加到.gitignore中。
- 構建時代碼替換：環(huán)境變量在構建時會被靜態(tài)替換，避免在代碼中動態(tài)拼接。
// ? 正確 - 靜態(tài)可分析
const url = import.meta.env.VITE_API_URL;
// ? 錯誤 - 動態(tài)key無法生效
const key = 'VITE_API_URL'; const url = import.meta.env[key];
7. 常見問題與解決方案
7.1 環(huán)境變量未生效的排查步驟
- 確認變量名以VITE_為前綴（或自定義前綴）
- 檢查文件名是否符合.env.[mode]規(guī)范
- 確認–mode參數(shù)與文件名中的mode一致
- 重啟開發(fā)服務器（環(huán)境變量更改需重啟生效）
- 檢查是否存在更高優(yōu)先級的.env文件覆蓋
7.2 模式（Mode）與NODE_ENV的區(qū)別
這是一個常見的混淆點：
- 模式（Mode）：由–mode參數(shù)指定，決定加載哪個.env文件
- NODE_ENV：Node.js環(huán)境變量，影響構建優(yōu)化
重要提示：PROD/DEV由NODE_ENV決定，而MODE由–mode參數(shù)決定。例如，執(zhí)行vite build --mode staging時：
- import.meta.env.MODE為"staging"
- import.meta.env.PROD為true（因為構建命令默認設置NODE_ENV=production）
8. DEV/PROD/MODE 深度解析
在 Vue3 + Vite 項目中，多環(huán)境配置（開發(fā)、測試、預發(fā)布、生產）是日常開發(fā)的高頻場景。很多開發(fā)者容易混淆 import.meta.env.DEV、import.meta.env.PROD 與 NODE_ENV 的關系，甚至嘗試手動修改它們，導致構建產物體積爆炸或性能下降。
本文基于實戰(zhàn)經驗，總結了核心機制、常見誤區(qū)及最佳實踐方案
8.1、核心機制速查表
Vite 的環(huán)境變量判定是編譯時靜態(tài)替換，而非運行時動態(tài)判斷。
| 命令場景 | 執(zhí)行指令 | import.meta.env.DEV | import.meta.env.PROD | import.meta.env.MODE | process.env.NODE_ENV (內部) | 說明 |
|---|---|---|---|---|---|---|
| 本地開發(fā) | npm run dev | true | false | 'development' | 'development' | 啟動開發(fā)服務器，支持 HMR |
| 生產構建 | npm run build | false | true | 'production' | 'production' | 默認生產構建，代碼壓縮、Tree-shaking |
| 預發(fā)布構建 | npm run build:staging (vite build --mode staging) | false | true | 'staging' | 'production' | 關鍵點：依然是生產構建邏輯，僅 Mode 不同 |
| 測試構建 | vite build --mode test | false | true | 'test' | 'production' | 同上，用于區(qū)分不同的 API 地址或配置 |
?? 核心結論：只要執(zhí)行的是 vite build 命令，無論 --mode 是什么，DEV 永遠為 false，PROD 永遠為 true。這是由構建工具底層決定的，無法通過配置文件覆蓋。
8.2 高頻易錯點與誤區(qū)分析表
| 易錯點/誤區(qū) | ? 錯誤做法/理解 | ?? 導致的嚴重后果 | ? 正確解決方案 |
|---|---|---|---|
| 誤區(qū) 1：Staging 環(huán)境需設為開發(fā)模式 | 在 .env.staging 中手動設置 NODE_ENV=development，試圖保留調試信息。 | 1. 代碼體積爆炸：Tree-shaking 失效，所有 console.log 和調試代碼被打包。 2. 性能下降：Vue 運行時保留開發(fā)檢查，渲染變慢。 3. 安全風險：暴露詳細堆棧和源碼邏輯。 | 保持默認。vite build 會自動將 NODE_ENV 設為 production。 如需調試信息，通過自定義變量控制（見下文）。 |
| 誤區(qū) 2：手動修改 DEV/PROD 值 | 試圖在代碼或配置中手動賦值 import.meta.env.DEV = true。 | 無效且報錯。這兩個值是 Vite 在編譯時注入的只讀常量，運行時無法修改。 | 使用 import.meta.env.MODE 來判斷具體業(yè)務環(huán)境（如 staging, test）。 |
| 誤區(qū) 3：混淆 MODE 與 PROD | 認為 staging 環(huán)境下 import.meta.env.PROD 應該是 false。 | 導致代碼邏輯錯誤。例如：if (!PROD) { initMock() } 在 staging 環(huán)境意外執(zhí)行了 Mock 邏輯。 | 明確認知：Staging 也是生產構建。區(qū)分環(huán)境請用 MODE === 'staging'。 |
| 誤區(qū) 4：依賴 process.env | 在代碼大量使用 process.env.NODE_ENV 進行判斷。 | 雖然 Vite 做了兼容，但推薦統(tǒng)一使用 import.meta.env 以獲得更好的類型提示和 Tree-shaking 支持。 | 全局替換為 import.meta.env.DEV / import.meta.env.PROD / import.meta.env.MODE。 |
| 誤區(qū) 5：SourceMap 配置不當 | 為了在 Staging 調試，強行不壓縮代碼或設 NODE_ENV=dev。 | 構建時間大幅增加，且產物不適合部署。 | 在 vite.config.ts 中根據 mode 動態(tài)開啟 build.sourcemap，保持代碼壓縮。 |
8.3 、總結
- 信任 Vite 的自動化：DEV 和 PROD 是由命令 (dev vs build) 決定的，不要試圖手動干預。
- 用 MODE
區(qū)分環(huán)境：development、staging、production 的區(qū)別在于 import.meta.env.MODE 和加載的
.env.[mode] 文件。 - Staging 也是 Production：預發(fā)布環(huán)境必須經過生產構建流程（壓縮、Tree-shaking），以保證與正式上線環(huán)境的一致性。
- 自定義變量解決特殊需求：需要調試日志或 SourceMap？請使用 VITE_ 前綴變量或在 vite.config.ts 中根據mode 動態(tài)配置，絕對不要設置 NODE_ENV=development。
總結
Vue3+Vite的環(huán)境變量管理系統(tǒng)提供了靈活的多環(huán)境配置方案。通過合理利用.env文件、正確理解模式與NODE_ENV的區(qū)別、遵循安全最佳實踐，可以構建出適應不同部署環(huán)境的健壯應用。
關鍵要點：
- 使用VITE_前綴定義客戶端環(huán)境變量
- 通過–mode參數(shù)指定運行環(huán)境
- 利用TypeScript獲得智能提示
- 遵循安全最佳實踐，保護敏感信息
掌握這些知識點后，您將能夠高效地管理Vue3+Vite項目的多環(huán)境配置，確保應用在不同環(huán)境下都能正確運行。
到此這篇關于Vue3+Vite環(huán)境變量與多環(huán)境配置詳解的文章就介紹到這了,更多相關Vue3+Vite環(huán)境變量與多環(huán)境配置內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
Vue3中ref數(shù)組的監(jiān)聽實現(xiàn)方式
Vue3中監(jiān)聽ref定義的數(shù)組,需根據監(jiān)聽需求選擇合適的監(jiān)聽方法,對于空數(shù)組,推薦使用深度監(jiān)聽來捕捉數(shù)組內部變化,同時,確保修改數(shù)組的方式是響應式的,以保證監(jiān)聽器能正常工作,根據具體需求,可以選擇直接深度監(jiān)聽、監(jiān)聽數(shù)組長度變化或提取屬性監(jiān)聽等方案2025-10-10
如何使用Vue3實現(xiàn)文章內容中多個"關鍵詞"標記高亮顯示
高亮顯示是我們日常開發(fā)中經常會遇到的需求,下面這篇文章主要給大家介紹了關于如何使用Vue3實現(xiàn)文章內容中多個"關鍵詞"標記高亮顯示的相關資料,文中通過實例代碼介紹的非常詳細,需要的朋友可以參考下2022-11-11
在使用?Vue.js?開發(fā)單頁應用?(SPA)?的過程中,開發(fā)者經常會遇到兩個常見問題,頁面切換時出現(xiàn)短暫的空白屏幕,以及刷新頁面時返回?404?錯誤,下面我們就來講講這兩個問題該如何將解決吧2025-05-05
elementui中tabel組件的scope.$index的使用及說明
這篇文章主要介紹了elementui中tabel組件的scope.$index的使用及說明，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-10-10
Vue+ECharts實現(xiàn)中國地圖的繪制及各省份自動輪播高亮顯示
這篇文章主要介紹了Vue+ECharts實現(xiàn)中國地圖的繪制以及拖動、縮放和各省份自動輪播高亮顯示,本文給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2021-12-12
這篇文章主要為大家詳細介紹了Vue3響應式核心之reactive的相關知識，文中的示例代碼講解詳細，對我們學習Vue3有一定的幫助，需要的可以參考一下2023-04-04
在使用vue框架的過程中,我們經常需要給一些數(shù)據做一些初始化處理,這時候我們常用的就是在created與mounted選項中作出處理,這篇文章主要給大家介紹了關于Vue中created與mounted區(qū)別的相關資料,其中部分知識點可能是我們日常工作會見到或用到的,需要的朋友可以參考下2022-06-06
這篇文章主要介紹了Vue中使用插槽（slot）、聚類插槽，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2019-04-04
這篇文章主要介紹了Vue之監(jiān)聽方法案例詳解,本篇文章通過簡要的案例,講解了該項技術的了解與使用,以下就是詳細內容,需要的朋友可以參考下2021-07-07
vue vuex vue-rouert后臺項目——權限路由（適合初學）
這篇文章主要介紹了vue vuex vue-rouert后臺項目——權限路由，通過本文可以很清除的捋清楚vue+vuex+vue-router的關系，本版本非常簡單，適合初學者,需要的朋友可以參考下2017-12-12