多环境配置实战指南：从环境隔离到配置管理的全流程优化

你是否曾因开发环境与生产环境配置不一致而导致线上故障？是否经历过切换环境时需要手动修改十多处配置的繁琐过程？又是否因敏感配置泄露而引发安全隐患？在现代软件开发中，多环境配置管理已成为影响开发效率和系统稳定性的关键因素。本文将以RuoYi-Vue3项目为基础，通过"问题诊断→方案设计→实施步骤→场景应用→优化策略"的完整框架，帮助你构建专业的多环境配置体系，解决配置冲突、提升开发效率、保障系统安全。

诊断环境配置痛点：识别多环境管理中的关键问题

剖析配置混乱的根源：从症状到病因

环境配置问题往往表现为多种症状，但其根源通常集中在几个核心方面。开发环境中正常运行的功能到测试环境突然报错，可能是环境变量未正确隔离；生产环境出现的神秘bug在本地无法复现，很可能是配置与环境不匹配；多人协作时频繁出现的配置冲突，则预示着缺乏统一的配置管理规范。

环境变量就像快递地址，不同环境需要不同的收货信息。开发环境是你的家庭地址，测试环境是公司前台，生产环境则是客户的收货地址。如果把所有地址写在同一张纸条上，不标注清楚，快递员（应用程序）就会送错地方，导致"物品丢失"（程序异常）。

量化环境配置问题的影响：数据驱动的分析

配置管理不当会带来显著的效率损失和风险成本。根据行业统计，开发团队平均有23%的时间用于解决环境相关问题，而环境配置错误导致的线上故障占比高达35%。在RuoYi-Vue3这类企业级应用中，一个配置错误可能导致整个权限系统失效，影响所有用户的正常使用。

快速检查清单：

• 团队是否存在"配置文件本地修改后忘记同步"的情况
• 环境切换是否需要修改超过3处配置
• 最近3个月是否发生过因环境配置导致的线上问题
• 是否能在30秒内完成任意环境的切换
• 敏感配置是否明文存储在代码仓库中

设计隔离边界：环境变量分层策略

构建三级环境变量体系：基础版实现

环境变量的分层设计是实现隔离的基础。我们可以将配置分为三个层级：

1. 系统级变量：如NODE_ENV、VITE_MODE等框架或构建工具必需的变量
2. 应用级变量：如API地址、应用标题等全局配置
3. 功能级变量：如特定模块的开关、第三方服务密钥等

在RuoYi-Vue3项目根目录创建以下配置文件：

# 开发环境 (.env.dev)
VITE_ENV_LEVEL = 'development'
VITE_API_BASE_URL = '/dev-api'
VITE_APP_TITLE = '若依管理系统-开发环境'
VITE_LOG_LEVEL = 'debug'
VITE_FEATURE_MOCK = 'true'

# 测试环境 (.env.test)
VITE_ENV_LEVEL = 'testing'
VITE_API_BASE_URL = '/test-api'
VITE_APP_TITLE = '若依管理系统-测试环境'
VITE_LOG_LEVEL = 'info'
VITE_FEATURE_MOCK = 'false'

# 生产环境 (.env.prod)
VITE_ENV_LEVEL = 'production'
VITE_API_BASE_URL = '/api'
VITE_APP_TITLE = '若依管理系统'
VITE_LOG_LEVEL = 'warn'
VITE_FEATURE_MOCK = 'false'

⚠️ 注意事项：所有客户端环境变量必须以VITE_为前缀，否则Vite构建工具会自动忽略这些变量，导致运行时无法访问。

环境变量作用域控制：进阶版设计

进阶的环境变量设计需要考虑作用域和生命周期：

// src/utils/env-scope.js
export const useEnvScope = () => {
  // 运行时环境变量（客户端可见）
  const runtimeEnv = {
    apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
    appTitle: import.meta.env.VITE_APP_TITLE,
    logLevel: import.meta.env.VITE_LOG_LEVEL
  }
  
  // 构建时环境变量（仅构建过程可见）
  const buildEnv = {
    // 这些变量不会出现在客户端代码中
    enableSourceMap: process.env.ENABLE_SOURCE_MAP === 'true',
    buildTimestamp: new Date().toISOString()
  }
  
  return { runtimeEnv, buildEnv }
}

💡 专家建议：将环境变量分为"构建时注入"和"运行时读取"两类。构建时变量用于控制打包行为（如是否生成sourcemap），运行时变量用于应用逻辑（如API地址）。这种区分可以减少客户端暴露的配置信息，提高安全性。

快速检查清单：

• 是否区分了构建时变量和运行时变量
• 敏感配置是否避免使用VITE_前缀
• 每个环境是否有独立的配置文件
• 配置文件是否添加了必要的注释说明
• 是否定义了环境变量的默认值

实施多环境构建流程：从配置到部署的全链路实现

Vite多环境配置实现：RuoYi-Vue3项目实战

Vite提供了强大的环境模式支持，我们可以通过修改vite.config.js实现多环境构建：

// vite.config.js
import { defineConfig, loadEnv } from 'vite'
import path from 'path'
import createVitePlugins from './vite/plugins'

export default defineConfig(({ mode }) => {
  // 加载对应环境的配置文件
  const env = loadEnv(mode, process.cwd(), 'VITE_')
  
  return {
    base: env.VITE_ENV_LEVEL === 'production' ? '/' : '/',
    plugins: createVitePlugins(env),
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src'),
        '~': path.resolve(__dirname, '.')
      }
    },
    server: {
      port: 80,
      host: true,
      open: true,
      proxy: {
        [env.VITE_API_BASE_URL]: {
          target: env.VITE_PROXY_TARGET || 'http://localhost:8080',
          changeOrigin: true,
          rewrite: (path) => path.replace(new RegExp(`^${env.VITE_API_BASE_URL}`), '')
        }
      }
    },
    build: {
      // 根据环境设置不同的构建选项
      sourcemap: env.VITE_ENV_LEVEL !== 'production',
      minify: env.VITE_ENV_LEVEL === 'production' ? 'terser' : false,
      rollupOptions: {
        output: {
          // 不同环境生成不同的输出目录
          dir: `dist/${env.VITE_ENV_LEVEL}`
        }
      }
    }
  }
})

然后修改package.json中的 scripts 配置：

{
  "scripts": {
    "dev": "vite --mode dev",
    "build:test": "vite build --mode test",
    "build:prod": "vite build --mode prod",
    "preview:test": "vite preview --mode test",
    "preview:prod": "vite preview --mode prod"
  }
}

Vite与Webpack环境处理差异对比：框架选择指南

不同构建工具的环境配置机制有显著差异，选择时需考虑项目需求：

特性	Vite	Webpack	适用场景
环境变量加载	构建时通过loadEnv显式加载	通过DefinePlugin注入	Vite更灵活，Webpack更成熟
热更新速度	基于原生ESM，速度快	需要刷新页面，速度较慢	开发环境Vite优势明显
配置复杂度	配置简洁，约定大于配置	配置复杂，高度可定制	简单项目选Vite，复杂项目选Webpack
环境切换	通过--mode参数一键切换	需要手动修改配置文件	Vite切换更便捷
生态系统	较新，持续成长	成熟，插件丰富	特殊构建需求可能需要Webpack

💡 专家建议：对于RuoYi-Vue3这类中大型项目，Vite的开发体验优势明显，但如果需要复杂的构建流程（如多入口、特殊资源处理），Webpack可能仍是更好的选择。可以考虑开发环境用Vite提高效率，生产构建用Webpack确保稳定性。

快速检查清单：

• 是否正确配置了不同环境的构建命令
• 代理设置是否根据环境变量动态调整
• 构建输出目录是否按环境分离
• 是否为不同环境设置了合适的优化选项
• 构建脚本是否添加了必要的错误处理

场景化环境配置应用：解决实际业务问题

动态主题切换：基于环境变量的UI定制

利用环境变量实现不同环境的视觉区分，帮助开发和测试人员快速识别当前环境：

// src/utils/theme.js
export const setupEnvironmentTheme = () => {
  const env = import.meta.env.VITE_ENV_LEVEL;
  const html = document.documentElement;
  
  // 移除所有环境相关类
  html.classList.remove('env-dev', 'env-test', 'env-prod');
  
  // 根据当前环境添加对应的类
  html.classList.add(`env-${env}`);
  
  // 设置环境标识样式
  const envIndicator = document.createElement('div');
  envIndicator.id = 'env-indicator';
  envIndicator.textContent = {
    development: '开发环境',
    testing: '测试环境',
    production: '生产环境'
  }[env];
  
  // 根据环境设置不同颜色
  envIndicator.style.backgroundColor = {
    development: '#409EFF', // 蓝色
    testing: '#E6A23C', // 橙色
    production: '#F56C6C'  // 红色
  }[env];
  
  // 如果已存在则先移除
  const existing = document.getElementById('env-indicator');
  if (existing) existing.remove();
  
  document.body.appendChild(envIndicator);
}

在src/assets/styles/ruoyi.scss中添加环境主题样式：

#env-indicator {
  position: fixed;
  top: 0;
  right: 0;
  color: white;
  padding: 2px 8px;
  font-size: 12px;
  z-index: 9999;
}

// 开发环境样式
.env-dev {
  --el-color-primary: #409EFF;
  // 其他开发环境特有样式
}

// 测试环境样式
.env-test {
  --el-color-primary: #E6A23C;
  // 其他测试环境特有样式
}

功能特性开关：基于环境的功能控制

使用环境变量实现不同环境的功能开关，避免在生产环境暴露测试功能：

// src/utils/feature.js
export const useFeature = () => {
  const env = import.meta.env.VITE_ENV_LEVEL;
  
  // 功能开关配置
  const features = {
    // 开发环境特有功能
    devTools: env === 'development',
    
    // 测试环境特有功能
    performanceMonitor: ['development', 'testing'].includes(env),
    
    // 所有环境都有的功能，但行为可能不同
    errorTracking: true,
    
    // 生产环境禁用的功能
    mockData: import.meta.env.VITE_FEATURE_MOCK === 'true',
    
    // A/B测试功能
    newDashboard: env !== 'production' || import.meta.env.VITE_FEATURE_NEW_DASHBOARD === 'true'
  };
  
  // 功能访问控制函数
  const isFeatureEnabled = (featureName) => {
    // 记录功能访问日志
    console.log(`Feature access: ${featureName} - ${features[featureName] ? 'enabled' : 'disabled'}`);
    return features[featureName];
  };
  
  return { features, isFeatureEnabled };
}

在组件中使用功能开关：

<template>
  <div class="dashboard">
    <div v-if="isFeatureEnabled('newDashboard')">
      <!-- 新仪表盘组件 -->
      <NewDashboard />
    </div>
    <div v-else>
      <!-- 旧仪表盘组件 -->
      <LegacyDashboard />
    </div>
    
    <!-- 开发工具仅在开发环境显示 -->
    <DevTools v-if="isFeatureEnabled('devTools')" />
  </div>
</template>

<script setup>
import { useFeature } from '@/utils/feature';
const { isFeatureEnabled } = useFeature();
</script>

跨环境数据迁移方案：安全高效的数据同步

不同环境间的数据迁移是常见需求，特别是从开发环境向测试环境迁移测试数据。以下是一个安全的数据迁移脚本：

// scripts/migrate-data.js
const fs = require('fs');
const path = require('path');
const axios = require('axios');
require('dotenv').config();

// 环境配置
const environments = {
  development: {
    apiUrl: process.env.DEV_API_URL || 'http://localhost:8080/dev-api',
    token: process.env.DEV_TOKEN
  },
  testing: {
    apiUrl: process.env.TEST_API_URL || 'http://localhost:8080/test-api',
    token: process.env.TEST_TOKEN
  },
  production: {
    apiUrl: process.env.PROD_API_URL || 'http://localhost:8080/api',
    token: process.env.PROD_TOKEN
  }
};

// 需要迁移的数据类型
const dataTypes = [
  { name: 'dict', endpoint: '/system/dict/data/list' },
  { name: 'menu', endpoint: '/system/menu/list' },
  { name: 'role', endpoint: '/system/role/list' }
];

/**
 * 从源环境导出数据
 */
async function exportData(sourceEnv, dataType) {
  try {
    console.log(`从${sourceEnv}环境导出${dataType.name}数据...`);
    const { apiUrl, token } = environments[sourceEnv];
    
    const response = await axios({
      method: 'get',
      url: `${apiUrl}${dataType.endpoint}`,
      headers: { 'Authorization': `Bearer ${token}` }
    });
    
    // 保存数据到文件
    const dataDir = path.join(__dirname, 'migrate-data');
    if (!fs.existsSync(dataDir)) {
      fs.mkdirSync(dataDir);
    }
    
    const filePath = path.join(dataDir, `${dataType.name}-${sourceEnv}-${new Date().toISOString().split('T')[0]}.json`);
    fs.writeFileSync(filePath, JSON.stringify(response.data, null, 2));
    
    console.log(`数据导出成功: ${filePath}`);
    return filePath;
  } catch (error) {
    console.error(`导出${dataType.name}数据失败:`, error.message);
    throw error;
  }
}

/**
 * 向目标环境导入数据
 */
async function importData(targetEnv, dataType, filePath) {
  try {
    console.log(`向${targetEnv}环境导入${dataType.name}数据...`);
    const { apiUrl, token } = environments[targetEnv];
    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
    
    // 根据数据类型选择合适的导入接口
    let importEndpoint = '';
    switch (dataType.name) {
      case 'dict':
        importEndpoint = '/system/dict/data/import';
        break;
      case 'menu':
        importEndpoint = '/system/menu/import';
        break;
      case 'role':
        importEndpoint = '/system/role/import';
        break;
      default:
        throw new Error(`不支持的数据类型: ${dataType.name}`);
    }
    
    await axios({
      method: 'post',
      url: `${apiUrl}${importEndpoint}`,
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      data: data
    });
    
    console.log(`${dataType.name}数据导入成功`);
  } catch (error) {
    console.error(`导入${dataType.name}数据失败:`, error.message);
    throw error;
  }
}

// 执行迁移
async function runMigration() {
  const sourceEnv = process.argv[2] || 'development';
  const targetEnv = process.argv[3] || 'testing';
  const dataType = process.argv[4];
  
  if (!sourceEnv || !targetEnv) {
    console.log('用法: node migrate-data.js <source-env> <target-env> [data-type]');
    console.log('示例: node migrate-data.js development testing dict');
    process.exit(1);
  }
  
  try {
    // 验证环境是否存在
    if (!environments[sourceEnv]) throw new Error(`源环境不存在: ${sourceEnv}`);
    if (!environments[targetEnv]) throw new Error(`目标环境不存在: ${targetEnv}`);
    
    // 选择要迁移的数据类型
    const typesToMigrate = dataType 
      ? dataTypes.filter(t => t.name === dataType)
      : dataTypes;
      
    if (typesToMigrate.length === 0) {
      throw new Error(`没有找到要迁移的数据类型: ${dataType}`);
    }
    
    // 执行迁移
    for (const type of typesToMigrate) {
      const filePath = await exportData(sourceEnv, type);
      await importData(targetEnv, type, filePath);
    }
    
    console.log('数据迁移完成!');
  } catch (error) {
    console.error('迁移失败:', error.message);
    process.exit(1);
  }
}

runMigration();

⚠️ 注意事项：数据迁移是高风险操作，特别是向生产环境迁移时。务必先在测试环境验证迁移脚本，执行前备份目标环境数据，并确保迁移账号具有适当的权限。

快速检查清单：

• 环境主题是否能清晰区分不同环境
• 功能开关是否按预期控制功能可见性
• 数据迁移脚本是否包含错误处理和日志记录
• 敏感数据在迁移过程中是否加密传输
• 是否有回滚机制应对迁移失败情况

环境配置故障排查：构建诊断决策树

环境配置故障排查决策树：系统化问题定位

环境配置问题的排查可以通过以下决策树系统化进行：

1. 症状识别

   • 是构建错误还是运行时错误？
   • 错误是否与API请求相关？
   • 是否所有环境都有问题还是特定环境？

2. 环境变量检查

   • 变量是否正确注入？console.log(import.meta.env)
   • 变量名是否以VITE_为前缀？
   • 配置文件是否在正确位置？

3. 构建配置检查

   • 构建命令是否指定了正确的--mode参数？
   • vite.config.js是否正确处理环境变量？
   • 代理配置是否正确映射API路径？

4. 网络请求检查

   • 实际请求的URL是否符合预期？
   • 跨域问题是否正确配置？
   • 后端服务是否在预期地址运行？

5. 依赖与缓存检查

   • node_modules是否有冲突？尝试删除重新安装
   • Vite缓存是否导致问题？使用--force参数重建
   • 环境变量是否有缓存？重启开发服务器

实用诊断脚本：自动化问题检测

以下是几个实用的环境配置诊断脚本：

1. 环境变量验证脚本 (scripts/check-env.js)：

#!/usr/bin/env node
const fs = require('fs');
const path = require('path');

// 预期的环境变量列表
const expectedEnvVars = [
  'VITE_ENV_LEVEL',
  'VITE_API_BASE_URL',
  'VITE_APP_TITLE',
  'VITE_LOG_LEVEL',
  'VITE_FEATURE_MOCK'
];

// 检查环境文件
function checkEnvFiles() {
  const envFiles = ['.env.dev', '.env.test', '.env.prod'];
  let allOk = true;
  
  console.log('=== 环境配置文件检查 ===');
  
  for (const file of envFiles) {
    const filePath = path.join(process.cwd(), file);
    if (!fs.existsSync(filePath)) {
      console.error(`❌ 缺少环境配置文件: ${file}`);
      allOk = false;
      continue;
    }
    
    console.log(`\n检查文件: ${file}`);
    const content = fs.readFileSync(filePath, 'utf8');
    const missingVars = [];
    
    for (const varName of expectedEnvVars) {
      if (!content.includes(varName)) {
        missingVars.push(varName);
      }
    }
    
    if (missingVars.length === 0) {
      console.log('✅ 所有必要变量都已配置');
    } else {
      console.error(`❌ 缺少必要变量: ${missingVars.join(', ')}`);
      allOk = false;
    }
  }
  
  return allOk;
}

// 主函数
function main() {
  const envOk = checkEnvFiles();
  
  if (!envOk) {
    console.error('\n❌ 环境配置检查未通过，请修复上述问题');
    process.exit(1);
  }
  
  console.log('\n✅ 环境配置检查通过');
  process.exit(0);
}

main();

2. 构建产物分析脚本 (scripts/analyze-build.js)：

#!/usr/bin/env node
const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');

// 分析不同环境的构建产物
function analyzeBuilds() {
  const modes = ['dev', 'test', 'prod'];
  const results = {};
  
  console.log('=== 构建产物分析 ===');
  
  for (const mode of modes) {
    console.log(`\n分析环境: ${mode}`);
    
    // 构建项目
    try {
      console.log('正在构建...');
      execSync(`npm run build:${mode}`, { stdio: 'ignore' });
    } catch (error) {
      console.error(`❌ 构建失败: ${error.message}`);
      results[mode] = { success: false };
      continue;
    }
    
    // 检查构建目录
    const buildDir = path.join(process.cwd(), `dist/${mode}`);
    if (!fs.existsSync(buildDir)) {
      console.error('❌ 构建目录不存在');
      results[mode] = { success: false };
      continue;
    }
    
    // 检查关键文件
    const indexPath = path.join(buildDir, 'index.html');
    if (!fs.existsSync(indexPath)) {
      console.error('❌ 缺少index.html文件');
      results[mode] = { success: false };
      continue;
    }
    
    // 检查环境变量是否正确注入
    const indexContent = fs.readFileSync(indexPath, 'utf8');
    const envVars = [
      `VITE_ENV_LEVEL=${mode}`,
      `VITE_API_BASE_URL=/` + (mode === 'prod' ? '' : `${mode}-`) + `api`
    ];
    
    let varsOk = true;
    for (const envVar of envVars) {
      if (!indexContent.includes(envVar)) {
        console.error(`❌ 环境变量未正确注入: ${envVar}`);
        varsOk = false;
      }
    }
    
    // 计算构建大小
    const buildSize = execSync(`du -sh ${buildDir}`).toString().split('\t')[0];
    
    results[mode] = {
      success: varsOk,
      buildSize,
      buildDir
    };
    
    if (varsOk) {
      console.log(`✅ 构建成功，大小: ${buildSize}`);
    }
  }
  
  // 生成报告
  console.log('\n=== 构建分析报告 ===');
  for (const mode in results) {
    const result = results[mode];
    if (result.success) {
      console.log(`✅ ${mode}: 成功 (${result.buildSize})`);
    } else {
      console.log(`❌ ${mode}: 失败`);
    }
  }
}

analyzeBuilds();

💡 专家建议：将这些诊断脚本集成到CI/CD流程中，在每次构建前自动运行环境检查，及早发现配置问题。同时，可以将脚本添加到package.json的scripts中，方便开发人员手动执行：

{
  "scripts": {
    "check-env": "node scripts/check-env.js",
    "analyze-build": "node scripts/analyze-build.js"
  }
}

快速检查清单：

• 是否能通过决策树定位大多数配置问题
• 诊断脚本是否能正确识别缺失的环境变量
• 构建产物分析是否能发现环境变量注入问题
• 是否将诊断脚本集成到开发流程中
• 团队成员是否了解基本的配置故障排查流程

环境配置自动化：CI/CD集成与配置即代码

环境配置CI/CD流水线：GitHub Actions实现

将环境配置管理集成到CI/CD流程中，实现配置的自动化测试和部署：

# .github/workflows/env-config.yml
name: 环境配置检查与构建

on:
  push:
    branches: [ main, develop ]
    paths:
      - '.env.*'
      - 'vite.config.js'
      - 'package.json'
      - '.github/workflows/env-config.yml'
  pull_request:
    branches: [ main, develop ]
    paths:
      - '.env.*'
      - 'vite.config.js'
      - 'package.json'

jobs:
  env-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: 设置Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          cache: 'npm'
          
      - name: 安装依赖
        run: npm ci
        
      - name: 环境配置检查
        run: npm run check-env
        
      - name: 构建测试
        run: npm run analyze-build

  deploy-dev:
    needs: env-check
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: 设置Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          cache: 'npm'
          
      - name: 安装依赖
        run: npm ci
        
      - name: 构建开发环境
        run: npm run build:test
        
      - name: 部署到开发服务器
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.DEV_SSH_KEY }}
          ARGS: "-rltgoDzvO --delete"
          SOURCE: "dist/test/"
          REMOTE_HOST: ${{ secrets.DEV_HOST }}
          REMOTE_USER: ${{ secrets.DEV_USER }}
          TARGET: "/www/ruoyi/test"

  deploy-prod:
    needs: env-check
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production  # 需要手动批准
    steps:
      - uses: actions/checkout@v3
      
      - name: 设置Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
          cache: 'npm'
          
      - name: 安装依赖
        run: npm ci
        
      - name: 构建生产环境
        run: npm run build:prod
        
      - name: 部署到生产服务器
        uses: easingthemes/ssh-deploy@main
        env:
          SSH_PRIVATE_KEY: ${{ secrets.PROD_SSH_KEY }}
          ARGS: "-rltgoDzvO --delete"
          SOURCE: "dist/production/"
          REMOTE_HOST: ${{ secrets.PROD_HOST }}
          REMOTE_USER: ${{ secrets.PROD_USER }}
          TARGET: "/www/ruoyi/prod"

配置即代码：环境配置的版本控制策略

将环境配置视为代码进行管理，实现配置的可追溯和审计：

1. 配置文件组织：

/config
  /templates          # 配置模板
    .env.dev.tpl
    .env.test.tpl
    .env.prod.tpl
  /scripts            # 配置生成脚本
    generate-env.js
  .gitignore          # 忽略实际配置文件
  README.md           # 配置说明文档

2. 配置生成脚本：

// config/scripts/generate-env.js
const fs = require('fs');
const path = require('path');
const dotenv = require('dotenv');

// 加载基础配置
const baseConfig = dotenv.parse(fs.readFileSync(path.join(__dirname, '../.env.base')));

// 环境列表
const environments = ['dev', 'test', 'prod'];

// 生成环境配置文件
environments.forEach(env => {
  // 加载环境特定配置
  const envConfigPath = path.join(__dirname, `../env/${env}.env`);
  const envConfig = fs.existsSync(envConfigPath) 
    ? dotenv.parse(fs.readFileSync(envConfigPath))
    : {};
  
  // 合并配置（环境配置优先于基础配置）
  const mergedConfig = { ...baseConfig, ...envConfig };
  
  // 加载模板文件
  const templatePath = path.join(__dirname, `../templates/.env.${env}.tpl`);
  let template = fs.readFileSync(templatePath, 'utf8');
  
  // 替换模板变量
  Object.keys(mergedConfig).forEach(key => {
    const placeholder = `{{${key}}}`;
    template = template.replace(new RegExp(placeholder, 'g'), mergedConfig[key]);
  });
  
  // 写入目标文件
  const targetPath = path.join(__dirname, `../../.env.${env}`);
  fs.writeFileSync(targetPath, template);
  console.log(`生成配置文件: ${targetPath}`);
});

console.log('所有环境配置文件生成完成');

3. 配置模板示例 (.env.prod.tpl)：

# 生产环境配置文件
# 自动生成，请勿手动修改
# 生成时间: {{GENERATE_TIME}}

VITE_ENV_LEVEL = 'production'
VITE_API_BASE_URL = '{{API_BASE_URL}}'
VITE_APP_TITLE = '若依管理系统'
VITE_LOG_LEVEL = 'warn'
VITE_FEATURE_MOCK = 'false'
VITE_API_TIMEOUT = '{{API_TIMEOUT}}'
VITE_MAX_UPLOAD_SIZE = '{{MAX_UPLOAD_SIZE}}'

⚠️ 注意事项：敏感配置（如API密钥、数据库密码）不应存储在代码仓库中。应使用CI/CD系统的secret功能或配置管理服务（如Vault）来管理这些敏感信息。

快速检查清单：

• CI/CD流程是否包含环境配置检查步骤
• 是否实现了不同环境的自动部署
• 配置文件是否通过模板生成而非手动编辑
• 敏感配置是否从代码仓库中移除
• 是否有配置变更的审计记录

环境配置健康度评估：量化与优化

环境配置健康度评分表：10项关键指标

设计一个量化的环境配置健康度评分体系，帮助团队评估和改进配置管理：

评估指标	权重	评分标准	得分
环境隔离完整性	15%	开发/测试/生产环境完全隔离，无硬编码配置	0-15
配置文件规范性	10%	配置文件命名统一，格式规范，注释完整	0-10
敏感信息处理	20%	敏感配置未明文存储，使用安全管理方式	0-20
配置自动化程度	15%	配置生成、部署、切换是否自动化	0-15
环境切换便捷性	10%	环境切换所需步骤和时间	0-10
配置文档完整性	10%	是否有完善的配置说明和使用文档	0-10
配置变更控制	10%	配置变更是否有审核和版本控制	0-10
故障排查能力	5%	是否有配置问题诊断工具和流程	0-5
跨环境一致性	5%	不同环境配置结构和变量是否一致	0-5
性能与安全优化	0%	配置是否考虑性能和安全最佳实践	0-5
总分	100%		0-100

多环境切换命令生成器：提升开发效率

创建一个便捷的环境切换工具，帮助开发人员快速切换开发环境：

#!/bin/bash
# scripts/env-switcher.sh

# 环境列表
ENVIRONMENTS=("dev" "test" "prod")

# 显示当前环境
current_env() {
  if [ -f .env ]; then
    grep VITE_ENV_LEVEL .env | cut -d '=' -f 2 | tr -d "' "
  else
    echo "未设置环境"
  fi
}

# 切换环境
switch_env() {
  local env=$1
  
  # 检查环境是否有效
  if [[ ! " ${ENVIRONMENTS[@]} " =~ " ${env} " ]]; then
    echo "错误: 无效的环境 '$env'，可用环境: ${ENVIRONMENTS[*]}"
    return 1
  fi
  
  # 检查环境文件是否存在
  if [ ! -f ".env.${env}" ]; then
    echo "错误: 环境文件 .env.${env} 不存在"
    return 1
  fi
  
  # 备份当前.env文件
  if [ -f .env ]; then
    mv .env .env.bak
  fi
  
  # 复制环境文件
  cp ".env.${env}" .env
  
  echo "已切换到${env}环境"
  current_env
}

# 显示帮助信息
show_help() {
  echo "环境切换工具"
  echo "用法: env-switcher [命令] [环境]"
  echo
  echo "命令:"
  echo "  current   显示当前环境"
  echo "  switch    切换环境"
  echo "  list      列出所有环境"
  echo "  help      显示帮助信息"
  echo
  echo "示例:"
  echo "  env-switcher switch test   切换到测试环境"
  echo "  env-switcher current       显示当前环境"
}

# 主逻辑
case "$1" in
  current)
    current_env
    ;;
  switch)
    if [ -z "$2" ]; then
      echo "错误: 请指定环境"
      show_help
      exit 1
    fi
    switch_env "$2"
    ;;
  list)
    echo "可用环境: ${ENVIRONMENTS[*]}"
    ;;
  help|*)
    show_help
    ;;
esac

将脚本添加到package.json：

{
  "scripts": {
    "env:current": "bash scripts/env-switcher.sh current",
    "env:switch": "bash scripts/env-switcher.sh switch",
    "env:list": "bash scripts/env-switcher.sh list"
  }
}

使用示例：

# 切换到测试环境
npm run env:switch test

# 查看当前环境
npm run env:current

# 列出所有环境
npm run env:list

快速检查清单：

• 环境配置健康度评分是否达到80分以上
• 环境切换是否能在30秒内完成
• 团队成员是否都能熟练使用环境切换工具
• 配置健康度是否定期评估和改进
• 环境切换是否有明确的操作文档

行业最佳实践与演进路线：从初级到高级

多环境配置的5条最佳实践

1. 严格的环境隔离原则：开发、测试、生产环境必须完全隔离，包括配置、数据和基础设施。环境之间的数据迁移必须通过自动化工具进行，并经过严格测试。

2. 配置集中管理：所有环境配置应集中存储和管理，避免分散在代码中。使用配置模板和生成工具，确保配置的一致性和可维护性。

3. 敏感信息保护：密码、密钥等敏感配置绝不能存储在代码仓库中，应使用环境变量、配置服务或密钥管理系统进行管理，并限制访问权限。

4. 配置即代码：将配置视为代码进行版本控制，实现配置变更的可追溯性和审计能力。每次配置变更都应经过代码审查流程。

5. 自动化与标准化：环境配置的生成、部署、切换应实现自动化，减少人工操作。建立标准化的配置规范和操作流程，确保团队成员遵循一致的实践。

环境配置演进路线图：从初级到高级

初级阶段：基础隔离

• 手动维护多个环境配置文件
• 通过注释区分不同环境的配置
• 手动修改配置文件切换环境
• 本地开发环境与生产环境分离

关键指标：环境切换时间 < 5分钟，配置相关bug每月 < 5个

中级阶段：自动化管理

• 使用构建工具的环境模式功能
• 实现配置生成自动化
• 环境切换命令行工具
• CI/CD集成环境检查
• 敏感配置加密存储

关键指标：环境切换时间 < 30秒，配置相关bug每月 < 2个，配置变更审计率100%

高级阶段：配置平台化

• 专用配置管理服务（如Nacos、Apollo）
• 动态配置更新（无需重新部署）
• 配置变更审批流程
• 配置使用监控和告警
• 多租户配置隔离

关键指标：配置变更生效时间 < 1分钟，配置相关bug每年 < 2个，配置健康度评分 > 90分

3个常见误区警示

1. 过度配置：试图为每个环境创建大量独特配置，导致维护困难。实际上，大多数配置在不同环境中应该保持一致，只需要修改少量环境特定参数。

2. 配置硬编码：在代码中直接写入环境特定值，而不是使用环境变量。这会导致环境切换困难，增加部署风险。

3. 忽视配置测试：将配置视为静态文件而不进行测试。实际上，配置变更应该像代码变更一样进行测试，验证其在目标环境中的正确性。

环境配置演进路线图：从手动管理到平台化管理的发展过程

总结：构建稳健的多环境配置体系

多环境配置管理是现代软件开发不可或缺的一部分，直接影响开发效率、系统稳定性和安全性。通过本文介绍的"问题诊断→方案设计→实施步骤→场景应用→优化策略"框架，你可以构建一个专业、高效的环境配置体系。

从基础的环境变量分层设计，到高级的CI/CD集成和配置平台化，每个阶段都有明确的目标和实施路径。记住，环境配置不是一次性工作，而是一个持续优化的过程。随着项目规模和团队的增长，配置管理策略也需要不断演进。

通过采用本文介绍的最佳实践，你可以显著减少环境相关问题，提高开发效率，确保系统在不同环境中的一致性和稳定性。最终，一个良好的环境配置体系将成为项目成功的重要基础，让团队能够专注于业务功能开发，而不是环境问题排查。