在uni-app项目中实现多环境变量配置的实践方案

背景介绍

在uni-app项目开发过程中，特别是针对原生APP打包的场景，开发者经常需要根据不同的环境（如开发环境、测试环境、生产环境等）使用不同的配置参数。这些参数可能包括API接口地址、应用标识、第三方服务密钥等。传统的.env文件配置方式在H5和小程序平台能够很好地工作，但在原生APP打包时却存在一些限制。

问题分析

uni-app项目基于Vite构建工具，默认支持.env文件的环境变量配置。Vite提供了.env、.env.production等文件来区分不同环境。然而，当需要为原生APP打包时，特别是通过HBuilder工具进行云打包时，开发者会遇到以下挑战：

1. 无法直接通过命令行参数指定不同的.env文件
2. 云打包流程中难以动态切换环境配置
3. 需要同时修改manifest.json中的相关配置
4. 不同环境可能需要不同的应用包名和签名配置

解决方案

方案一：Vite插件动态注入环境变量

对于Vue3项目，可以通过编写自定义Vite插件来实现环境变量的动态注入。这种方法的核心思路是在构建过程中根据平台信息动态设置环境变量。

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

let hasRenamed = false;
export default defineConfig({
  plugins: [{
    name: 'vite-plugin-rename-env',
    enforce: 'pre',
    configResolved(config) {
      const isIos = process.env.UNI_APP_PLATFORM === 'ios'
      if (isIos && !hasRenamed) {
        process.env.VITE_CURRENT_MODE = 'ios'
      }
    }
  },
  uni()],
});

这种方式的优点是不需要修改构建命令，缺点是灵活性有限，难以应对复杂的多环境场景。

方案二：构建前脚本预处理

更完善的解决方案是在构建前通过Node.js脚本进行预处理，这种方法可以实现：

1. 根据参数生成特定的.env.production.local文件
2. 动态修改manifest.json中的配置参数
3. 调整cli打包参数配置
4. 调用cli命令完成最终打包

实现步骤如下：

1. 在package.json中配置自定义脚本命令

{
  "scripts": {
    "build:safemode:dev": "node ./build/app-prepare.js mode=production_dev && node ./build/app-build.js"
  }
}

2. 创建预处理脚本app-prepare.js，主要功能包括：

   • 解析命令行参数确定目标环境
   • 复制对应的.env文件为.env.production.local
   • 修改manifest.json中的相关配置项
   • 生成cli打包所需的参数配置文件

3. 创建构建脚本app-build.js，调用官方cli命令完成打包

实践建议

1. 环境变量管理：建立清晰的.env文件命名规范，如.env.dev、.env.stage、.env.prod等

2. 配置同步：确保manifest.json中的配置与环境变量保持同步，特别是应用ID、版本号等关键信息

3. 脚本健壮性：预处理脚本应包含完善的错误处理和日志输出，便于排查问题

4. 版本控制：将.env.example文件纳入版本控制，但敏感配置应通过.env.local管理并加入.gitignore

5. 多平台适配：考虑不同平台(iOS/Android)可能需要的特殊处理

注意事项

1. 鸿蒙Next平台目前可能不支持这种方案，需要单独处理
2. 云打包场景下可能需要调整策略
3. 敏感信息应妥善保管，避免泄露
4. 复杂场景可能需要结合CI/CD流程实现自动化

总结

通过构建前脚本预处理的方式，开发者可以灵活地实现uni-app项目在多环境下的原生APP打包需求。这种方法虽然需要一定的脚本编写工作，但提供了最大的灵活性和可控性，能够满足企业级应用的复杂配置需求。在实际项目中，建议根据团队的技术栈和CI/CD流程选择最适合的实现方式。