UniApp+Vite环境变量配置实战：从原理到避坑指南

在跨平台开发中，环境变量管理是区分开发、测试和生产环境的关键。当UniApp遇上Vite，这套组合虽然强大，但环境变量的配置却暗藏玄机。本文将带你深入Vite环境变量的加载机制，揭示UniApp项目中的特殊处理方式，并提供可复用的多环境解决方案。

1. Vite环境变量核心机制解析

Vite的环境变量系统基于dotenv实现，但比传统方案更智能。理解其工作原理是解决配置问题的第一步。

文件加载规则：

.env                # 基础配置（所有环境加载）
.env.local          # 本地覆盖（被git忽略）
.env.[mode]         # 特定模式配置
.env.[mode].local   # 特定模式本地覆盖

优先级从低到高依次为：.env < .env.local < .[mode] < .[mode].local。当运行vite --mode staging时，会优先加载.env.staging.local中的配置。

变量暴露规则：

• 只有以VITE_开头的变量才会暴露给客户端代码
• 内置变量（无需声明即可使用）：

  import.meta.env.MODE     // 当前模式（development/production等）
  import.meta.env.BASE_URL // 部署基础路径
  import.meta.env.PROD     // 是否生产环境
  import.meta.env.DEV      // 是否开发环境
  

警告：在UniApp项目中，BASE_URL有特殊含义，它表示静态资源基础路径，不要与自定义的API基础地址混淆。

2. UniApp项目的特殊处理

UniApp对Vite的集成有其特殊性，这导致标准Vite配置在某些情况下失效。以下是关键差异点：

2.1 HBuilderX与CLI项目的区别

特性	HBuilderX项目	CLI项目
模式支持	仅限development/production	支持自定义模式(--mode xxx)
配置文件加载	需绝对路径指定	自动从根目录加载
环境变量作用域	受构建工具限制	完全遵循Vite规则

HBuilderX项目示例配置：

// vite.config.js
import { loadEnv } from 'vite'
export default defineConfig({
  plugins: [uni()],
  define: {
    // 必须使用绝对路径
    'process.env': loadEnv(process.env.NODE_ENV, __dirname)
  }
})

2.2 多平台编译的变量注入

UniApp需要处理各小程序平台的差异，推荐使用条件编译：

// 获取环境变量示例
function getBaseUrl() {
  // #ifdef H5
  return import.meta.env.VITE_H5_API_URL
  // #endif
  // #ifdef MP-WEIXIN
  return import.meta.env.VITE_MP_API_URL
  // #endif
}

3. 实战：配置测试环境变量

让我们通过具体案例实现测试环境配置：

3.1 文件结构

project-root/
├── .env                # 基础配置
├── .env.development    # 开发环境
├── .env.production     # 生产环境
├── .env.test           # 测试环境
└── vite.config.js

3.2 测试环境配置

# .env.test
VITE_API_BASE=https://test.api.example.com
VITE_ENV_NAME=Test
VITE_DEBUG_MODE=true

3.3 package.json配置

{
  "scripts": {
    "dev": "uni -p h5",
    "build": "uni build -p h5",
    "build:test": "uni build -p h5 --mode test",
    "serve:test": "uni -p h5 --mode test"
  }
}

3.4 类型支持（TypeScript）

// env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_BASE: string
  readonly VITE_ENV_NAME: string
  readonly VITE_DEBUG_MODE: string
}

4. 常见问题排查指南

当环境变量不生效时，按照以下步骤排查：

1. 检查文件位置：确保.env文件在项目根目录
2. 验证模式匹配：运行命令是否包含--mode xxx
3. 前缀确认：变量名是否以VITE_开头
4. 优先级检查：是否有.local文件覆盖了配置
5. 重启服务：修改.env文件需要重启开发服务器

典型错误示例：

// 错误：缺少VITE_前缀
API_URL=https://api.example.com  // 不会被暴露

// 错误：错误的位置
console.log(process.env.VITE_API_URL) // 应该用import.meta.env

5. 高级配置技巧

5.1 自定义变量前缀

// vite.config.js
export default defineConfig({
  envPrefix: ['UNI_', 'VITE_'], // 同时支持两种前缀
  plugins: [uni()]
})

5.2 动态加载配置

// 根据模式动态配置
export default defineConfig(({ mode }) => ({
  define: {
    __APP_VERSION__: JSON.stringify(loadEnv(mode, process.cwd()).VITE_APP_VERSION)
  }
}))

5.3 多环境自动化

{
  "scripts": {
    "build:all": "npm run build:dev && npm run build:test && npm run build:prod",
    "build:dev": "uni build --mode development",
    "build:test": "uni build --mode test",
    "build:prod": "uni build --mode production"
  }
}

6. 安全与最佳实践

1. 敏感信息保护：

   • 永远不要将数据库密码等敏感信息放入VITE_前缀变量
   • 服务端专用变量使用无前缀或自定义前缀

2. Git忽略规则：

   *.local
   .env.*.local
   

3. 跨团队协作：

   # .env.example (模板文件)
   VITE_API_BASE=YOUR_API_BASE
   VITE_ENV_NAME=development
   

4. 环境验证：

   // 启动时检查必要变量
   if (!import.meta.env.VITE_API_BASE) {
     console.error('Missing required env variables')
   }
   

通过以上配置，UniApp+Vite项目可以实现灵活的多环境管理。记住关键点：模式决定配置、前缀控制暴露、位置影响加载。当遇到问题时，从这三个维度入手排查，通常能找到解决方案。