Umi.js 环境变量配置问题解析与解决方案

环境变量配置的基本原理

在Umi.js项目中，环境变量是前端开发中常用的配置方式，它允许开发者根据不同的运行环境（如开发、测试、生产）动态切换应用配置。Umi.js基于dotenv实现了环境变量加载机制，通过.env文件来管理不同环境下的变量配置。

常见问题现象

许多开发者在配置环境变量时会遇到这样的问题：按照官方文档创建了.env文件并设置了变量，但在代码中通过process.env访问时却得到undefined。这种情况通常发生在以下场景：

1. 创建了自定义环境文件如.env.demo
2. 在启动命令中设置了REACT_APP_ENV和UMI_ENV为对应环境值
3. 运行时却无法获取到预期的环境变量值

问题根源分析

这个问题的核心在于Umi.js的环境变量机制。Umi.js的环境变量配置需要通过三个层级的传递：

1. package.json中的scripts命令设置的环境变量
2. .umirc.ts或config/config.ts中的define配置
3. 最终才能在src源代码中访问到

这种设计是为了保证构建时的环境变量能够正确注入到最终产物中。

解决方案

要解决环境变量无法获取的问题，需要按照以下步骤进行配置：

1. 在项目根目录创建对应的.env文件，如.env.demo
2. 在package.json的scripts中正确设置环境变量：

"scripts": {
  "start:demo": "cross-env REACT_APP_ENV=demo UMI_ENV=demo umi dev"
}

3. 在.umirc.ts或config/config.ts中配置define：

export default {
  define: {
    'process.env.UMI_APP_TEST_URL': process.env.UMI_APP_TEST_URL
  }
}

最佳实践建议

1. 环境变量命名建议统一前缀，如UMI_APP_，以避免与其他变量冲突
2. 敏感信息不要直接放在.env文件中，应该通过CI/CD流程注入
3. 为不同环境创建对应的.env文件，如.env.dev、.env.test、.env.prod
4. 在团队中建立统一的变量命名规范

高级配置技巧

对于更复杂的需求，可以考虑以下方案：

1. 使用环境变量组合，通过.env.local覆盖部分配置
2. 在config/config.ts中实现动态环境变量加载逻辑
3. 通过插件机制扩展环境变量功能

通过正确理解和配置Umi.js的环境变量机制，开发者可以轻松实现多环境配置管理，提高项目的可维护性和部署灵活性。