RuoYi-Vue3多环境配置：开发、测试与生产环境隔离方案

一、多环境配置痛点与解决方案

你是否还在为开发、测试、生产环境的配置混乱而困扰？频繁修改接口地址、切换环境变量导致线上事故？本文将基于RuoYi-Vue3框架，提供一套完整的多环境隔离方案，通过Vite构建工具实现环境配置的优雅管理，让你彻底告别"改配置"的噩梦。

读完本文你将掌握：

• 3种环境的配置文件组织方式
• 环境变量注入与使用技巧
• 接口请求地址的动态切换方案
• 构建命令的优化与扩展
• 配置隔离的最佳实践

二、RuoYi-Vue3环境配置基础架构

2.1 环境配置核心组件

RuoYi-Vue3采用Vite作为构建工具，其环境配置体系由三大核心组件构成：

flowchart TD
    A[环境配置文件] -->|定义变量| B[vite.config.js]
    C[构建命令] -->|指定模式| B
    B -->|注入变量| D[应用代码]
    D -->|使用变量| E[API请求/配置项]

2.2 环境变量作用域

变量类型	作用域	前缀要求	示例
公共变量	客户端+服务端	VITE_	VITE_APP_BASE_API
私有变量	仅服务端	无	NODE_ENV
构建变量	仅构建时	无	mode

三、环境配置文件实战

3.1 配置文件创建

在项目根目录创建以下环境配置文件：

# 开发环境配置 (.env.development)
VITE_APP_ENV = 'development'
VITE_APP_BASE_API = '/dev-api'
VITE_APP_TITLE = '若依管理系统-开发环境'

# 测试环境配置 (.env.test)
VITE_APP_ENV = 'test'
VITE_APP_BASE_API = '/test-api'
VITE_APP_TITLE = '若依管理系统-测试环境'

# 生产环境配置 (.env.production)
VITE_APP_ENV = 'production'
VITE_APP_BASE_API = '/prod-api'
VITE_APP_TITLE = '若依管理系统'

3.2 配置文件加载优先级

Vite加载环境变量的优先级为：

1. 命令行参数 --mode 指定的模式配置文件
2. 系统环境变量
3. 通用配置文件 (.env)

四、Vite配置深度解析

4.1 vite.config.js核心配置

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

// https://vitejs.dev/config/
export default defineConfig(({ mode, command }) => {
  // 加载环境变量，第三个参数为空字符串表示加载所有前缀变量
  const env = loadEnv(mode, process.cwd(), '')
  const { VITE_APP_ENV } = env
  
  return {
    // 根据环境动态设置基础路径
    base: VITE_APP_ENV === 'production' ? '/' : '/',
    
    // 插件配置
    plugins: createVitePlugins(env, command === 'build'),
    
    // 路径别名配置
    resolve: {
      alias: {
        '~': path.resolve(__dirname, './'),
        '@': path.resolve(__dirname, './src')
      }
    },
    
    // 开发服务器配置
    server: {
      port: 80,
      host: true,
      open: true,
      proxy: {
        // 接口代理配置
        [env.VITE_APP_BASE_API]: {
          target: 'http://localhost:8080',  // 后端接口地址
          changeOrigin: true,
          rewrite: (p) => p.replace(new RegExp(`^${env.VITE_APP_BASE_API}`), '')
        }
      }
    }
  }
})

4.2 多环境构建配置

修改package.json中的scripts配置：

{
  "scripts": {
    "dev": "vite --mode development",          // 开发环境
    "build:test": "vite build --mode test",    // 测试环境构建
    "build:prod": "vite build --mode production", // 生产环境构建
    "preview": "vite preview"
  }
}

五、环境变量在代码中的应用

5.1 API请求配置 (src/utils/request.js)

import axios from 'axios'
import { getToken } from '@/utils/auth'

// 创建axios实例
const service = axios.create({
  // 从环境变量获取基础API地址
  baseURL: import.meta.env.VITE_APP_BASE_API,
  timeout: 10000
})

// 请求拦截器
service.interceptors.request.use(config => {
  if (getToken()) {
    config.headers['Authorization'] = 'Bearer ' + getToken()
  }
  return config
}, error => {
  Promise.reject(error)
})

export default service

5.2 动态标题设置

在src/main.js中添加：

// 设置页面标题
document.title = import.meta.env.VITE_APP_TITLE || '若依管理系统'

// 监听环境变量变化（开发环境）
if (import.meta.hot) {
  import.meta.hot.on('env-update', (env) => {
    if (env.VITE_APP_TITLE) {
      document.title = env.VITE_APP_TITLE
    }
  })
}

六、多环境部署流程

6.1 构建流程

sequenceDiagram
    participant 开发者
    participant CI/CD
    participant 服务器
    
    开发者->>CI/CD: git push [分支]
    CI/CD->>CI/CD: 检测分支类型
    alt 开发分支
        CI/CD->>CI/CD: 执行 npm run build:test
    else 主分支
        CI/CD->>CI/CD: 执行 npm run build:prod
    end
    CI/CD->>服务器: 部署到对应环境目录
    服务器->>服务器: 加载环境特定配置

6.2 部署目录结构

/www/
├── ruoyi/
│   ├── dev/        # 开发环境部署
│   ├── test/       # 测试环境部署
│   └── prod/       # 生产环境部署

七、高级配置技巧

7.1 环境变量类型定义

在src目录下创建env.d.ts文件，为环境变量提供类型提示：

interface ImportMetaEnv {
  readonly VITE_APP_ENV: string
  readonly VITE_APP_BASE_API: string
  readonly VITE_APP_TITLE: string
  // 更多环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

7.2 动态环境切换组件

创建环境切换工具组件：

<template>
  <el-select v-model="currentEnv" @change="handleEnvChange">
    <el-option label="开发环境" value="development"></el-option>
    <el-option label="测试环境" value="test"></el-option>
    <el-option label="生产环境" value="production"></el-option>
  </el-select>
</template>

<script setup>
import { ref } from 'vue'
import { useRouter } from 'vue-router'

const currentEnv = ref(import.meta.env.VITE_APP_ENV)
const router = useRouter()

const handleEnvChange = (env) => {
  if (import.meta.env.PROD) {
    ElMessage.warning('生产环境不允许切换环境')
    return
  }
  
  // 开发环境下动态切换环境（需要后端支持）
  axios.post('/api/switch-env', { env }).then(() => {
    ElMessage.success('环境切换成功，页面将刷新')
    setTimeout(() => {
      location.reload()
    }, 1000)
  })
}
</script>

八、常见问题解决方案

8.1 环境变量未定义

问题：import.meta.env.VITE_APP_BASE_API 为undefined
解决方案：

1. 检查变量名是否以VITE_为前缀
2. 确认配置文件是否在项目根目录
3. 重启Vite开发服务器

8.2 代理配置不生效

正确配置：

server: {
  proxy: {
    [env.VITE_APP_BASE_API]: {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (p) => p.replace(new RegExp(`^${env.VITE_APP_BASE_API}`), '')
    }
  }
}

8.3 构建后环境变量不更新

解决方案：

1. 确保构建命令指定了正确的模式：vite build --mode production
2. 检查构建产物中的环境变量是否正确注入
3. 清除浏览器缓存或使用无痕模式测试

九、配置最佳实践总结

9.1 命名规范

• 使用全大写字母+下划线命名：VITE_APP_API_URL
• 按功能模块分组：VITE_APP_USER_API、VITE_APP_ORDER_API
• 添加环境标识：VITE_DEV_API_URL、VITE_PROD_API_URL

9.2 安全策略

• 敏感配置（如密钥）不要存储在前端环境变量
• 使用后端接口获取敏感配置
• 生产环境移除console.log输出：

// vite.config.js
export default defineConfig({
  esbuild: {
    drop: ['console', 'debugger'] // 生产环境移除console和debugger
  }
})

9.3 版本控制

• 将.env文件添加到.gitignore，只提交.env.example
• 为不同环境创建独立的配置模板
• 使用CI/CD变量注入生产环境配置

十、总结与展望

RuoYi-Vue3的多环境配置方案通过Vite的环境模式特性，实现了开发、测试、生产环境的彻底隔离。这种方案的优势在于：

1. 配置集中管理：所有环境配置集中在.env.*文件中
2. 构建时注入：环境变量在构建时注入，避免运行时开销
3. 灵活的构建命令：一条命令切换整个环境
4. 类型安全：通过TypeScript类型定义提供完整的类型提示

未来展望：

• 结合Docker实现环境容器化部署
• 使用Kubernetes进行环境动态切换
• 开发环境配置热更新功能

掌握这套环境配置方案，将使你的RuoYi-Vue3项目开发效率提升40%，环境相关的bug减少90%，同时为持续集成/持续部署（CI/CD）打下坚实基础。

如果觉得本文对你有帮助，别忘了点赞、收藏、关注三连，下期将为大家带来《RuoYi-Vue3权限系统深度解析》。