Umi.js 环境变量 UMI_ENV 的使用注意事项

在 Umi.js 项目中，环境变量 UMI_ENV 是一个特殊变量，它决定了项目运行时加载哪些额外的配置文件。最近有开发者反馈，在命令行中设置的 UMI_ENV 值会被项目中的 .env 文件覆盖，这实际上是一个使用上的误区。

UMI_ENV 的特殊性

UMI_ENV 与其他环境变量不同，它专门用于控制 Umi.js 的多环境配置加载机制。根据官方设计，这个变量只能在命令行运行时指定，而不能在环境变量文件中定义。这是因为：

1. UMI_ENV 需要在项目启动的最早期就确定下来
2. 它会影响后续配置文件的加载逻辑
3. 如果允许在 .env 文件中定义，会导致配置加载顺序混乱

正确的使用方式

开发者应该在运行命令时直接指定 UMI_ENV，例如：

UMI_ENV=production umi dev

或者使用 cross-env 工具实现跨平台兼容：

cross-env UMI_ENV=production umi dev

环境变量优先级说明

在 Umi.js 中，环境变量的加载遵循以下优先级原则：

1. 命令行指定的环境变量（最高优先级）
2. .env.local 文件
3. .env.{UMI_ENV} 文件
4. .env 文件（最低优先级）

但 UMI_ENV 是个例外，它只能通过命令行指定，任何在 .env 文件中定义的 UMI_ENV 都会被忽略。

实际应用场景

在实际开发中，UMI_ENV 常用于以下场景：

1. 区分开发、测试和生产环境
2. 加载不同环境的特定配置
3. 实现多环境部署方案

例如，可以创建 config.production.ts 和 config.staging.ts 等不同环境的配置文件，然后通过 UMI_ENV 来指定加载哪个配置。

总结

理解 UMI_ENV 的特殊性对正确使用 Umi.js 的多环境功能至关重要。开发者应该避免在 .env 文件中定义 UMI_ENV，而应该始终通过命令行来指定。这种设计保证了配置加载的顺序性和一致性，是 Umi.js 框架的一个重要特性。