umi多环境配置：开发、测试、生产环境无缝切换

前言：为什么需要多环境配置？

在现代前端开发中，项目通常需要在多个环境中运行：开发环境（development）、测试环境（testing）、预发布环境（staging）和生产环境（production）。每个环境都有不同的配置需求：

• 开发环境：需要热重载、详细的错误信息、调试工具
• 测试环境：需要模拟数据、测试专用的API地址
• 生产环境：需要代码压缩、性能优化、安全的配置

umi框架提供了强大的多环境配置机制，让你能够轻松管理不同环境的配置差异。

umi环境配置的核心机制

1. 环境变量识别

umi基于NODE_ENV和UMI_ENV两个环境变量来识别当前运行环境：

// 环境判断逻辑
const isDev = process.env.NODE_ENV === 'development';
const isProd = process.env.NODE_ENV === 'production';
const env = process.env.UMI_ENV || ''; // 自定义环境标识

2. 配置文件优先级

umi支持多种配置文件格式，按以下优先级加载：

graph TD
    A[.umirc.ts] --> B[config/config.ts]
    B --> C[.umirc.${UMI_ENV}.ts]
    C --> D[config/config.${UMI_ENV}.ts]
    D --> E[环境变量覆盖]

实战：配置多环境项目

基础配置文件结构

首先创建基础的配置文件结构：

项目根目录/
├── config/
│   ├── config.ts          # 基础配置
│   ├── config.dev.ts      # 开发环境配置
│   ├── config.test.ts     # 测试环境配置
│   └── config.prod.ts     # 生产环境配置
├── .env                   # 全局环境变量
├── .env.development       # 开发环境变量
├── .env.testing           # 测试环境变量
└── .env.production        # 生产环境变量

基础配置文件示例

config/config.ts - 基础配置

import { defineConfig } from 'umi';

export default defineConfig({
  // 公共配置
  publicPath: '/',
  history: { type: 'browser' },
  routes: [
    { path: '/', component: 'index' },
    { path: '/users', component: 'users' },
  ],
  npmClient: 'pnpm',
});

config/config.dev.ts - 开发环境配置

import { defineConfig } from 'umi';

export default defineConfig({
  // 开发环境特有配置
  define: {
    'process.env.API_BASE': 'http://localhost:8000/api',
    'process.env.ENV': 'development',
  },
  devtool: 'cheap-module-source-map',
  mock: {
    include: ['src/mock/**/*.ts'],
  },
  fastRefresh: true,
});

config/config.test.ts - 测试环境配置

import { defineConfig } from 'umi';

export default defineConfig({
  define: {
    'process.env.API_BASE': 'https://test-api.example.com/api',
    'process.env.ENV': 'testing',
  },
  // 测试环境关闭mock
  mock: false,
  // 测试环境特定的插件配置
  extraBabelPlugins: [
    ['babel-plugin-istanbul', { extension: ['.ts', '.tsx'] }],
  ],
});

config/config.prod.ts - 生产环境配置

import { defineConfig } from 'umi';

export default defineConfig({
  define: {
    'process.env.API_BASE': 'https://api.example.com/api',
    'process.env.ENV': 'production',
  },
  // 生产环境优化配置
  jsMinifier: 'terser',
  cssMinifier: 'cssnano',
  manifest: {
    fileName: 'asset-manifest.json',
  },
  // 生产环境关闭sourcemap
  devtool: false,
  // CDN配置
  publicPath: 'https://cdn.example.com/',
});

环境变量文件配置

.env - 全局环境变量

# 项目基本信息
APP_NAME=My Umi App
APP_VERSION=1.0.0

# 通用API配置
API_TIMEOUT=10000
MAX_RETRY=3

.env.development - 开发环境

# 开发环境配置
NODE_ENV=development
UMI_ENV=dev
PORT=8000
HOST=localhost

# 开发环境API
API_BASE=http://localhost:8000/api
MOCK_ENABLED=true
DEBUG=true

.env.testing - 测试环境

# 测试环境配置
NODE_ENV=production
UMI_ENV=test
PORT=3000

# 测试环境API
API_BASE=https://test-api.example.com/api
MOCK_ENABLED=false
DEBUG=false

.env.production - 生产环境

# 生产环境配置
NODE_ENV=production
UMI_ENV=prod
PORT=80

# 生产环境API
API_BASE=https://api.example.com/api
MOCK_ENABLED=false
DEBUG=false

环境特定的运行时配置

动态配置加载

在代码中可以根据环境动态加载配置：

// src/utils/env.ts
export const getEnvConfig = () => {
  const env = process.env.UMI_ENV || 'dev';
  
  const configs = {
    dev: {
      apiBase: 'http://localhost:8000/api',
      logLevel: 'debug',
      features: ['mock', 'devTools'],
    },
    test: {
      apiBase: 'https://test-api.example.com/api',
      logLevel: 'info',
      features: ['analytics'],
    },
    prod: {
      apiBase: 'https://api.example.com/api',
      logLevel: 'warn',
      features: ['analytics', 'monitoring'],
    },
  };

  return configs[env] || configs.dev;
};

环境感知的组件

创建能够感知环境的React组件：

// src/components/EnvironmentAwareComponent.tsx
import React from 'react';
import { getEnvConfig } from '@/utils/env';

const EnvironmentAwareComponent: React.FC = () => {
  const envConfig = getEnvConfig();
  const isDevelopment = process.env.NODE_ENV === 'development';

  return (
    <div className="env-banner">
      <h3>当前环境: {process.env.UMI_ENV || 'development'}</h3>
      <p>API地址: {envConfig.apiBase}</p>
      {isDevelopment && (
        <div className="dev-features">
          <button onClick={() => console.log('开发工具')}>开发工具</button>
          <button onClick={() => alert('Mock数据')}>Mock功能</button>
        </div>
      )}
    </div>
  );
};

export default EnvironmentAwareComponent;

构建和部署脚本

package.json脚本配置

{
  "scripts": {
    "dev": "umi dev",
    "build:dev": "UMI_ENV=dev umi build",
    "build:test": "UMI_ENV=test umi build",
    "build:prod": "UMI_ENV=prod umi build",
    "start:dev": "UMI_ENV=dev umi dev",
    "start:test": "UMI_ENV=test PORT=3000 umi dev",
    "analyze": "ANALYZE=1 umi build"
  }
}

自动化部署脚本

#!/bin/bash
# deploy.sh

ENV=${1:-prod}

echo "开始部署到 $ENV 环境"

# 根据环境选择配置
case $ENV in
  dev)
    npm run build:dev
    DEPLOY_PATH="/var/www/dev"
    ;;
  test)
    npm run build:test  
    DEPLOY_PATH="/var/www/test"
    ;;
  prod)
    npm run build:prod
    DEPLOY_PATH="/var/www/prod"
    ;;
  *)
    echo "未知环境: $ENV"
    exit 1
    ;;
esac

# 部署逻辑
rsync -avz dist/ user@server:$DEPLOY_PATH/
echo "部署完成到 $DEPLOY_PATH"

环境配置最佳实践

1. 安全敏感信息处理

// 使用环境变量管理敏感信息
export default defineConfig({
  define: {
    'process.env.API_KEY': process.env.API_KEY || '',
    'process.env.DATABASE_URL': process.env.DATABASE_URL || '',
  },
});

2. 环境特定的插件配置

// 根据环境启用不同的插件
const plugins = [
  // 基础插件
  '@umijs/plugins/dist/initial-state',
  '@umijs/plugins/dist/model',
];

if (process.env.UMI_ENV === 'dev') {
  plugins.push('@umijs/plugins/dist/dva'); // 仅开发环境使用dva
}

export default defineConfig({
  plugins,
});

3. 环境检测工具函数

// src/utils/environment.ts
export const Environment = {
  isDev: () => process.env.NODE_ENV === 'development',
  isTest: () => process.env.UMI_ENV === 'test',
  isProd: () => process.env.NODE_ENV === 'production' && process.env.UMI_ENV === 'prod',
  
  getCurrent: () => {
    if (process.env.UMI_ENV) return process.env.UMI_ENV;
    return process.env.NODE_ENV === 'development' ? 'dev' : 'prod';
  },
  
  // 功能开关
  features: {
    mock: () => Environment.isDev() || process.env.MOCK_ENABLED === 'true',
    analytics: () => !Environment.isDev(),
    debug: () => Environment.isDev() || process.env.DEBUG === 'true',
  },
};

常见问题排查

环境变量未生效？

检查启动命令是否正确设置环境变量：

# 正确的方式
UMI_ENV=test npm run build

# 错误的方式（环境变量不会传递）
npm run build UMI_ENV=test

配置合并问题？

umi的配置合并遵循特定规则，可以使用console.log调试：

export default defineConfig(async () => {
  const config = {
    // 你的配置
  };
  
  if (process.env.UMI_ENV === 'dev') {
    console.log('开发环境配置加载');
  }
  
  return config;
});

总结

umi的多环境配置机制提供了灵活而强大的环境管理能力。通过合理使用环境变量、配置文件优先级和运行时检测，你可以实现：

• 🚀 无缝环境切换：通过简单的环境变量切换不同配置
• 🔒 安全隔离：敏感信息通过环境变量管理，不进入代码仓库
• ⚡ 性能优化：不同环境使用不同的优化策略
• 🐛 调试友好：开发环境提供完整的调试支持
• 📊 监控就绪：生产环境集成监控和分析工具

掌握umi的多环境配置，让你的应用在不同阶段都能发挥最佳性能，提升开发和部署效率。