概覽

在現(xiàn)代前端開發(fā)中，為不同的環(huán)境（如開發(fā)、測試、生產(chǎn)）配置不同的參數(shù)是基本需求。Vue3結(jié)合Vite構(gòu)建工具提供了一套清晰的環(huán)境變量管理機(jī)制。本文將詳細(xì)介紹如何在Vue3+Vite項(xiàng)目中配置和使用環(huán)境變量。

1. 環(huán)境變量基礎(chǔ)

1.1 什么是 import.meta.env？

在Vite項(xiàng)目中，環(huán)境變量通過特殊的 import.meta.env 對象暴露給客戶端代碼。這些變量在開發(fā)階段全局可用，在構(gòu)建時(shí)會被靜態(tài)替換，以便進(jìn)行優(yōu)化（如tree-shaking）。

Vite內(nèi)置了一些常用的環(huán)境變量：

• import.meta.env.MODE: 應(yīng)用運(yùn)行的模式（如 development、production）
• import.meta.env.BASE_URL: 部署應(yīng)用時(shí)的基本URL，由vite配置中的base選項(xiàng)決定
• import.meta.env.PROD: 是否運(yùn)行在生產(chǎn)環(huán)境（布爾值）
• import.meta.env.DEV: 是否運(yùn)行在開發(fā)環(huán)境（布爾值，始終與PROD相反）
• import.meta.env.SSR: 是否運(yùn)行在服務(wù)端渲染環(huán)境（布爾值）

1.2 環(huán)境變量的安全規(guī)則

Vite有一個重要的安全規(guī)則：只有以 VITE_ 為前綴的變量才會暴露給客戶端代碼。這是為了防止敏感信息（如數(shù)據(jù)庫密碼、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)境文件結(jié)構(gòu)與加載優(yōu)先級

Vite使用dotenv從環(huán)境目錄加載額外的環(huán)境變量，支持以下文件結(jié)構(gòu)：

•  .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（全局默認(rèn)配置）

所有環(huán)境共用配置

VITE_APP_TITLE=我的應(yīng)用
VITE_API_TIMEOUT=5000

開發(fā)環(huán)境

.env.development（開發(fā)環(huán)境）

VITE_APP_TITLE=我的應(yīng)用(開發(fā)版)
VITE_API_BASE_URL=http://localhost:3000/api
VITE_ENABLE_DEBUG=true

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

.env.production（生產(chǎn)環(huán)境）

VITE_APP_TITLE=我的應(yīng)用
VITE_API_BASE_URL=https://api.example.com
VITE_ENABLE_DEBUG=false

預(yù)發(fā)布環(huán)境

.env.staging（預(yù)發(fā)布環(huán)境）

VITE_APP_TITLE=我的應(yīng)用(預(yù)發(fā)布)
VITE_API_BASE_URL=https://staging-api.example.com
VITE_ENABLE_DEBUG=false

2.3 配置package.json腳本

在package.json中配置對應(yīng)環(huán)境的啟動和構(gòu)建命令：

{
  "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會自動加載對應(yīng)模式的環(huán)境變量文件。

3. 在代碼中使用環(huán)境變量

3.1 訪問環(huán)境變量

在Vue組件或JavaScript/TypeScript文件中，通過import.meta.env訪問環(huán)境變量：
// 獲取API基礎(chǔ)地址
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
// 環(huán)境判斷
if (import.meta.env.DEV) {
  console.log('開發(fā)環(huán)境，啟用調(diào)試工具');
}
// 獲取當(dāng)前模式
const currentMode = import.meta.env.MODE;
在Vue組件中的使用示例：
<template>
  <div>
    <h1>{{ appTitle }}</h1>
    <p>API地址: {{ apiUrl }}</p>
    <p>當(dāng)前環(huán)境: {{ isDev ? '開發(fā)環(huán)境' : '生產(chǎ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è)置第三個參數(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)境變量的智能提示，需要在項(xiàng)目中添加類型定義。

創(chuàng)建src/vite-env.d.ts文件：

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

interface ImportMetaEnv {
  // 內(nèi)置變量
  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. 高級技巧與最佳實(shí)踐

5.1 自定義環(huán)境文件目錄

默認(rèn)情況下，Vite在項(xiàng)目根目錄查找環(huán)境文件?？梢酝ㄟ^envDir配置項(xiàng)指定自定義目錄：

//vite.config.ts
import { defineConfig } from 'vite';
import path from 'path';
export default defineConfig({
  envDir: path.resolve(__dirname, './env'), // 指定環(huán)境文件目錄
});

5.2 運(yùn)行時(shí)配置覆蓋

為了實(shí)現(xiàn)"一次構(gòu)建，多處部署"，可以使用運(yùn)行時(shí)配置覆蓋技術(shù)：

public/config.js
window.__APP_CONFIG__ = {
  API_BASE_URL: "https://runtime-api.example.com",
  APP_TITLE: "我的應(yīng)用(運(yùn)行時(shí)配置)",
  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> <!-- 必須在應(yīng)用腳本之前加載 -->
  </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,
  
  // 應(yīng)用信息
  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)境變量驗(yàn)證

創(chuàng)建環(huán)境變量驗(yà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;
  }
}

// 應(yīng)用啟動時(shí)驗(yàn)證
EnvValidator.validate();

6. 安全注意事項(xiàng)

1. 敏感信息保護(hù)：切勿將密碼、Token等敏感信息放在VITE_開頭的變量中。
2. Git忽略配置：確保.env.local和*.local文件已添加到.gitignore中。
3. 構(gòu)建時(shí)代碼替換：環(huán)境變量在構(gòu)建時(shí)會被靜態(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)境變量未生效的排查步驟

1. 確認(rèn)變量名以VITE_為前綴（或自定義前綴）
2. 檢查文件名是否符合.env.[mode]規(guī)范
3. 確認(rèn)–mode參數(shù)與文件名中的mode一致
4. 重啟開發(fā)服務(wù)器（環(huán)境變量更改需重啟生效）
5. 檢查是否存在更高優(yōu)先級的.env文件覆蓋

7.2 模式（Mode）與NODE_ENV的區(qū)別

這是一個常見的混淆點(diǎn)：

• 模式（Mode）：由–mode參數(shù)指定，決定加載哪個.env文件
• NODE_ENV：Node.js環(huán)境變量，影響構(gòu)建優(yōu)化

重要提示：PROD/DEV由NODE_ENV決定，而MODE由–mode參數(shù)決定。例如，執(zhí)行vite build --mode staging時(shí)：

•  import.meta.env.MODE為"staging"
• import.meta.env.PROD為true（因?yàn)闃?gòu)建命令默認(rèn)設(shè)置NODE_ENV=production）

8. DEV/PROD/MODE 深度解析

在 Vue3 + Vite 項(xiàng)目中，多環(huán)境配置（開發(fā)、測試、預(yù)發(fā)布、生產(chǎn)）是日常開發(fā)的高頻場景。很多開發(fā)者容易混淆 import.meta.env.DEV、import.meta.env.PROD 與 NODE_ENV 的關(guān)系，甚至嘗試手動修改它們，導(dǎo)致構(gòu)建產(chǎn)物體積爆炸或性能下降。
本文基于實(shí)戰(zhàn)經(jīng)驗(yàn)，總結(jié)了核心機(jī)制、常見誤區(qū)及最佳實(shí)踐方案

8.1、核心機(jī)制速查表

Vite 的環(huán)境變量判定是編譯時(shí)靜態(tài)替換，而非運(yùn)行時(shí)動態(tài)判斷。

?? 核心結(jié)論：只要執(zhí)行的是 vite build 命令，無論 --mode 是什么，DEV 永遠(yuǎn)為 false，PROD 永遠(yuǎn)為 true。這是由構(gòu)建工具底層決定的，無法通過配置文件覆蓋。

8.2 高頻易錯點(diǎn)與誤區(qū)分析表

8.3 、總結(jié)

1. 信任 Vite 的自動化：DEV 和 PROD 是由命令 (dev vs build) 決定的，不要試圖手動干預(yù)。
2. 用 MODE
   區(qū)分環(huán)境：development、staging、production 的區(qū)別在于 import.meta.env.MODE 和加載的
   .env.[mode] 文件。
3. Staging 也是 Production：預(yù)發(fā)布環(huán)境必須經(jīng)過生產(chǎn)構(gòu)建流程（壓縮、Tree-shaking），以保證與正式上線環(huán)境的一致性。
4. 自定義變量解決特殊需求：需要調(diào)試日志或 SourceMap？請使用 VITE_ 前綴變量或在 vite.config.ts 中根據(jù)mode 動態(tài)配置，絕對不要設(shè)置 NODE_ENV=development。

總結(jié)

Vue3+Vite的環(huán)境變量管理系統(tǒng)提供了靈活的多環(huán)境配置方案。通過合理利用.env文件、正確理解模式與NODE_ENV的區(qū)別、遵循安全最佳實(shí)踐，可以構(gòu)建出適應(yīng)不同部署環(huán)境的健壯應(yīng)用。

關(guān)鍵要點(diǎn)：

• 使用VITE_前綴定義客戶端環(huán)境變量
• 通過–mode參數(shù)指定運(yùn)行環(huán)境
• 利用TypeScript獲得智能提示
• 遵循安全最佳實(shí)踐，保護(hù)敏感信息

掌握這些知識點(diǎn)后，您將能夠高效地管理Vue3+Vite項(xiàng)目的多環(huán)境配置，確保應(yīng)用在不同環(huán)境下都能正確運(yùn)行。

到此這篇關(guān)于Vue3+Vite環(huán)境變量與多環(huán)境配置詳解的文章就介紹到這了,更多相關(guān)Vue3+Vite環(huán)境變量與多環(huán)境配置內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論