uniapp環境變量最佳配置方案詳情 - 環境變量,API,生產環境,Vue.js,前端開發子丶不語博客

什麼是環境變量？

📝 生活中的環境變量類比

春晚小品表演的完整流程是一個非常生動的環境變量類比：

小品排練廳就像開發環境：可以隨意修改劇本，反覆排練，自由度高
劇場彩排就像測試環境：模擬真實演出，檢查笑點和配合，對應
聯排驗收就像預發佈環境：接近正式演出，領導驗收，最終調整
正式演出就像生產環境：必須完美呈現，全球直播，零容錯

春晚小品從排練到正式演出需要不同的場地、設備和狀態，軟件開發也需要根據不同環境使用不同的配置，這些配置就是環境變量。

開發中的環境變量實例

在UniApp開發中，我們同樣需要根據不同環境使用不同的配置：

場景1：API接口地址

✅ 開發環境：https://dev-api.example.com（開發人員測試用，數據可隨意修改）
🧪 測試環境：https://test-api.example.com（測試人員驗證用，數據相對穩定）
🚀 生產環境：https://api.example.com（正式用户使用，數據嚴格保護）

場景2：日誌記錄

✅ 開發環境：記錄所有日誌（包括調試信息），便於開發調試
🧪 測試環境：記錄關鍵日誌，便於測試定位問題
🚀 生產環境：僅記錄錯誤日誌，避免性能開銷和信息泄露

場景3：功能開關

✅ 開發環境：開啓所有新功能，包括未完成的實驗性功能
🧪 測試環境：開啓待測試的新功能
🚀 生產環境：僅開啓已驗證穩定的功能

場景4：第三方服務配置

✅ 開發環境：使用第三方服務的測試密鑰
🧪 測試環境：使用第三方服務的預發佈密鑰
🚀 生產環境：使用第三方服務的正式密鑰

企業常用環境分類

在企業實際開發中，通常會劃分多個環境來確保軟件質量和穩定性。以下是企業常用的環境分類：

uniapp環境變量最佳配置方案_生產環境

環境變量的定義

環境變量（Environment Variables）是在操作系統或應用程序運行時，用來存儲配置信息的動態值。在移動應用開發中，環境變量主要用於：

區分不同運行環境（開發、測試、生產）
管理API接口地址
配置第三方服務密鑰
控制功能開關
存儲敏感信息

為什麼需要環境變量？

避免硬編碼：將配置與代碼分離，便於維護和部署 安全管理：敏感信息不直接寫在代碼中，降低泄露風險 靈活切換：同一套代碼可以快速切換到不同環境 團隊協作：統一配置管理，避免開發人員之間的配置差異

UniApp傳統環境變量實現

在瞭解Vite+UniApp的環境變量配置前，我們先看看UniApp傳統的環境變量實現方式。

1. 基於小程序環境API的實現

UniApp作為跨平台框架，在小程序端可以利用小程序提供的API來獲取當前環境：

// 獲取當前小程序環境
try {
  const accountInfo = uni.getAccountInfoSync();
  const envVersion = accountInfo.miniProgram.envVersion;


  switch (envVersion) {
    case 'develop':
      console.log('當前是開發環境');
      break;
    case 'trial':
      console.log('當前是體驗版環境');
      break;
    case 'release':
      console.log('當前是正式版環境');
      break;
  }
} catch (e) {
  console.error('獲取環境信息失敗', e);
}

2. 自定義配置文件

在實際項目中，通常會創建一個配置文件，根據環境動態返回不同的配置：

let config = {};
  // 獲取當前環境信息
  const accountInfo = uni.getAccountInfoSync();
  const envVersion = accountInfo.miniProgram.envVersion;
  // 使用switch明確區分不同環境
  switch (envVersion) {
    case 'develop':
      config = {
        baseUrl: '開發版API地址',
        // 其他開發版專屬配置
      };
      break;
    case 'trial':
      // 體驗版配置
      config = {
        baseUrl: '體驗版API地址',
        // 其他體驗版專屬配置
      };
      break;  
    case 'release':
      // 正式版配置
      config = {
        baseUrl: '正式版API地址',
        // 其他正式版專屬配置
      };
      break; 
    default:
      // 默認配置（兜底方案）
      config = {
        baseUrl: '默認API地址',
        // 默認配置項
      };
  }
export default config;

3. 傳統方式的優缺點

優點：

實現簡單，易於理解
直接利用小程序平台能力
無需額外構建配置

缺點：

僅適用於小程序端，H5等其他平台需要額外處理
缺少構建時環境變量注入能力
配置集中，不利於分環境管理

Vite+UniApp環境變量配置

隨着Vite的普及，越來越多的UniApp項目開始使用Vite作為構建工具。Vite提供了強大的環境變量管理能力，讓我們可以在構建時注入環境變量。

1. Vite環境變量基礎

Vite使用.env系列文件來管理環境變量：

uniapp環境變量最佳配置方案_環境變量_02

2. 在UniApp+Vite項目中配置環境變量

步驟1：創建.env文件

在項目根目錄創建以下文件：

# .env.development - 開發環境
VITE_APP_NAME=UniApp開發環境
VITE_API_BASE_URL=https://api.example.com/dev
VITE_DEBUG=true


# .env.production - 生產環境  
VITE_APP_NAME=UniApp生產環境
VITE_API_BASE_URL=https://api.example.com/prod
VITE_DEBUG=false

步驟2：配置vite.config.js

在vite.config.js中添加環境變量配置：

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'


export default defineConfig({
  plugins: [uni()],
  // 環境變量配置
  define: {
    // 可以在這裏手動定義全局變量
    // '__APP_VERSION__': JSON.stringify('1.0.0')
  }
})

步驟3：在package.json中添加構建腳本

// package.json
{
  "scripts": {
    "dev:h5": "vite",
    "dev:mp-weixin": "vite --mode development",
    "build:h5": "vite build",
    "build:mp-weixin": "vite build --mode production"
  }
}

步驟4：在代碼中使用環境變量

console.log(import.meta.env.VITE_APP_NAME);
console.log(import.meta.env.VITE_API_BASE_URL);
console.log(import.meta.env.VITE_DEBUG);

3. 小程序環境與Vite環境的結合

在UniApp+Vite項目中，我們可以結合小程序的環境檢測和Vite的環境變量，實現更靈活的配置：

// src/common/config.js
// 引入Vite環境變量
const viteEnv = import.meta.env;


// 定義各環境配置
const envConfigs = {
  // 開發環境
  development: {
    baseUrl: viteEnv.VITE_API_BASE_URL || 'https://api.example.com/dev',
    uploadUrl: 'https://upload.example.com/dev',
    debug: viteEnv.VITE_DEBUG === 'true'
  },
  // 生產環境
  production: {
    baseUrl: viteEnv.VITE_API_BASE_URL || 'https://api.example.com/prod',
    uploadUrl: 'https://upload.example.com/prod',
    debug: viteEnv.VITE_DEBUG === 'true'
  }
};


// 獲取當前環境
let currentEnv = 'development';


// 小程序環境檢測
try {
  const accountInfo = uni.getAccountInfoSync();
  const envVersion = accountInfo.miniProgram.envVersion;


  if (envVersion === 'release') {
    currentEnv = 'production';
  } else if (envVersion === 'trial') {
    // 體驗版可以使用開發環境配置
    currentEnv = 'development';
  }
} catch (e) {
  // H5或其他平台使用Vite環境
  currentEnv = viteEnv.MODE;
}


export default envConfigs[currentEnv];

環境變量底層原理

1. Vite環境變量的處理流程

加載.env文件：Vite在啓動時根據--mode參數加載對應的.env文件
解析環境變量：將.env文件中的變量解析為JavaScript對象
注入環境變量：

開發環境：通過import.meta.env全局對象訪問
生產環境：在構建時將環境變量替換為具體值

安全檢查：Vite會自動忽略以NODE_開頭的環境變量，避免泄露Node.js環境信息

2. 環境變量的注入機制

開發環境：

Vite開發服務器啓動時，創建一個全局的import.meta.env對象
通過ES模塊的動態導入機制，將環境變量注入到代碼中
支持熱更新，修改.env文件後不需要重啓開發服務器

生產環境：

在構建階段，Vite使用rollup-plugin-replace插件
將代碼中的import.meta.env.VITE_*替換為具體的環境變量值
最終生成的代碼中不再包含環境變量引用，提高安全性

3. UniApp跨平台環境變量處理

UniApp作為跨平台框架，需要處理不同平台的環境差異：

uniapp環境變量最佳配置方案_生產環境_03

最佳實踐與注意事項

1. 環境變量命名規範

以VITE_開頭的變量會被Vite自動暴露給客户端
使用大寫字母和下劃線命名（如VITE_API_BASE_URL）
避免使用敏感詞作為變量名

2. 敏感信息管理

不要將敏感信息（如API密鑰、數據庫密碼）直接寫在.env文件中
對於需要保密的配置，考慮使用服務器端接口動態獲取
使用.env.local文件存儲本地開發配置，該文件會被git忽略

3. 跨平台兼容性

不同平台的環境檢測方式不同，需要做好兼容處理
小程序端優先使用平台提供的環境檢測API
H5和App端優先使用Vite環境變量

4. 構建腳本配置

// package.json -推薦的構建腳本配置
{
"scripts":{
"dev:h5":"vite",
"dev:mp-weixin":"vite --mode development",
"dev:mp-alipay":"vite --mode development",
"build:h5":"vite build --mode production",
"build:mp-weixin":"vite build --mode production",
"build:mp-alipay":"vite build --mode production",
"build:app-plus":"vite build --mode production"
}
}

5. 環境變量的調試

開發環境可以使用console.log(import.meta.env)打印所有環境變量
生產環境需要注意不要泄露敏感信息
可以使用條件編譯，在生產環境移除調試代碼

📚 總結

UniApp環境變量的管理方式隨着構建工具的發展而不斷演進：

傳統方式：基於小程序環境API的動態配置，實現簡單但跨平台支持有限
Vite方式：利用Vite的環境變量機制，實現構建時注入，支持跨平台
混合方式：結合小程序環境檢測和Vite環境變量，實現更靈活的配置管理

選擇合適的環境變量管理方式，需要根據項目的實際情況和需求來決定。對於使用Vite構建的UniApp項目，推薦使用Vite的環境變量機制，結合小程序環境檢測，實現一套統一的配置管理方案。

子丶不語博客

子丶不語博客

博客 / 詳情