Umi.js 环境变量配置的深度解析与实践指南

2025-05-14 14:31:32作者：宣聪麟

环境变量在Umi.js中的工作机制

Umi.js作为企业级前端应用框架，提供了灵活的环境变量管理机制。理解其工作原理对于项目配置至关重要。环境变量在Umi中分为两个层面：

Node.js运行时环境：这些变量在构建阶段可用，通过.env文件或命令行参数设置
浏览器运行时环境：这些变量会被注入到前端代码中，通过define配置实现

常见配置误区与解决方案

误区一：混淆环境变量作用域

许多开发者容易混淆Node.js环境变量和浏览器环境变量的使用场景。.env文件中定义的变量只能在构建阶段（如.umirc.ts配置文件中）通过process.env访问，而要在前端代码中使用，必须通过define配置显式注入。

误区二：错误使用UMI_ENV

UMI_ENV是一个特殊的环境变量，用于加载额外的配置文件。例如，设置UMI_ENV=dev会加载config/config.dev.ts，但要注意：

UMI_ENV不会自动加载.env.dev文件
配置文件优先级遵循特定规则，不是简单的覆盖关系

最佳实践方案

方案一：基于UMI_APP_前缀的自动注入

Umi.js约定以UMI_APP_为前缀的环境变量会自动注入到前端代码中：

在.env中定义：

UMI_APP_API_URL=https://api.example.com

在前端代码中直接使用：

const apiUrl = process.env.UMI_APP_API_URL

这种方式无需额外配置define，是最简洁的方案。

方案二：多环境精细化配置

对于需要更精细环境控制的场景，推荐结合UMI_ENV和多个配置文件：

修改package.json脚本：

{
  "scripts": {
    "start:dev": "cross-env UMI_ENV=dev umi dev",
    "start:test": "cross-env UMI_ENV=test umi dev"
  }
}

创建对应的配置文件：

config/config.dev.ts
config/config.test.ts

在配置文件中定义特定环境的变量：

// config.dev.ts
export default {
  define: {
    'process.env.API_BASE': '//localhost:8000'
  }
}

方案三：动态配置注入

对于需要在.umirc.ts中根据环境动态配置的场景：

// .umirc.ts
export default {
  define: {
    'process.env.API_BASE': 
      process.env.UMI_ENV === 'dev' 
        ? '//localhost:8000' 
        : '//api.example.com'
  }
}

调试技巧与常见问题排查

变量未生效检查清单：
- 确认变量名拼写完全一致（包括大小写）
- 检查配置文件加载顺序和优先级
- 确保重启开发服务器使配置生效
类型声明补充：对于自定义的全局变量，需要在项目中添加类型声明：
```
// typings.d.ts
declare const MY_GLOBAL_VAR: string;
```
构建产物分析：检查最终生成的代码中变量是否被正确替换，可使用umi build --analyze分析构建结果。