Vite多环境配置实战：从基础到高级应用

1. 为什么需要多环境配置

在Vue/Vite项目开发中，我们通常会遇到这样的场景：开发时使用mock数据，测试时需要连接测试服务器API，上线后又需要切换生产环境API地址。如果每次切换环境都手动修改代码，不仅效率低下，还容易出错。

多环境配置的核心价值在于：

• 隔离不同环境的变量和配置
• 自动化切换环境相关参数
• 避免人为操作失误导致的环境污染
• 提高团队协作效率

以一个电商项目为例，开发环境(dev)可能使用本地3000端口，测试环境(test)连接测试服务器，生产环境(prod)则指向线上域名。这三个环境的API地址、资源路径、调试模式等都可能不同。

2. Vite环境变量基础配置

2.1 环境变量文件命名规范

Vite使用dotenv从环境目录(默认为项目根目录)加载.env文件。推荐的文件命名规则：

code复制.env                # 所有环境都会加载
.env.local          # 本地覆盖，会被git忽略
.env.[mode]         # 指定模式加载(如.env.development)
.env.[mode].local   # 指定模式的本地覆盖

实际项目中常用的文件结构：

code复制├── .env
├── .env.development
├── .env.test
└── .env.production

2.2 变量命名与使用

环境变量需要以VITE_前缀开头才能在客户端代码中访问：

env复制# .env.development
VITE_API_BASE_URL=http://localhost:3000/api
VITE_DEBUG_MODE=true

在代码中通过import.meta.env访问：

javascript复制const apiUrl = import.meta.env.VITE_API_BASE_URL

重要提示：永远不要在客户端代码中暴露敏感信息如API密钥，即使有VITE_前缀保护

2.3 模式与命令关联

在package.json中配置脚本命令时，通过--mode参数指定环境：

json复制{
  "scripts": {
    "dev": "vite --mode development",
    "test": "vite --mode test",
    "build": "vite build --mode production",
    "build:test": "vite build --mode test"
  }
}

3. 多环境高级配置实战

3.1 环境特定配置文件

对于复杂项目，建议使用环境特定配置文件。创建config目录：

code复制config/
├── dev.env.js
├── test.env.js
└── prod.env.js

示例dev.env.js内容：

javascript复制module.exports = {
  baseUrl: 'http://localhost:3000',
  apiPrefix: '/api/v1',
  enableMock: true,
  analytics: false
}

在vite.config.js中动态加载配置：

javascript复制import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  const config = require(`./config/${mode}.env.js`)
  
  return {
    define: {
      __APP_CONFIG__: JSON.stringify(config)
    }
  }
})

3.2 条件编译与动态导入

根据环境变量实现条件编译：

javascript复制// 动态加载不同环境的API模块
const apiModule = import.meta.env.VITE_ENV === 'production' 
  ? await import('./api/prod.js')
  : await import('./api/dev.js')

3.3 CSS环境变量

Vite支持在CSS中使用环境变量：

css复制:root {
  --primary-color: env(VITE_PRIMARY_COLOR, #1890ff);
}

4. 常见问题与解决方案

4.1 环境变量未生效

排查步骤：

1. 确认变量名以VITE_开头
2. 检查.env文件是否放在项目根目录
3. 确认启动命令包含正确的--mode参数
4. 重启开发服务器（环境变量在启动时加载）

4.2 生产环境构建问题

典型错误：

bash复制[vite:define] Replacement for "import.meta.env.VITE_API_URL" must be a JSON string

解决方案：

javascript复制// vite.config.js
define: {
  'import.meta.env.VITE_API_URL': JSON.stringify(process.env.VITE_API_URL)
}

4.3 测试环境特殊处理

测试环境常见需求：

• 关闭代码压缩便于调试
• 保留console.log
• 生成sourcemap

配置示例：

javascript复制// vite.config.js
build: {
  minify: mode === 'test' ? false : 'esbuild',
  sourcemap: mode === 'test',
  terserOptions: {
    compress: {
      drop_console: mode !== 'test'
    }
  }
}

5. 最佳实践与优化建议

5.1 安全注意事项

1. 敏感信息处理：

• 使用服务器端环境变量而非前端环境变量存储密钥
• 考虑使用.env.local文件并加入.gitignore

2. 类型安全：

typescript复制// env.d.ts
interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string
  readonly VITE_ENV: 'development' | 'test' | 'production'
}

5.2 性能优化

1. 按需加载环境配置：

javascript复制const loadConfig = async () => {
  if (import.meta.env.VITE_ENV === 'production') {
    return import('./config/prod')
  }
  // ...
}

2. 构建时优化：

javascript复制// vite.config.js
build: {
  rollupOptions: {
    external: mode === 'production' ? ['mockjs'] : []
  }
}

5.3 团队协作规范

1. 文档模板：

markdown复制## 环境变量说明

| 变量名 | 说明 | 示例值 | 必需 |
|-------|------|-------|-----|
| VITE_API_BASE_URL | API基础路径 | http://localhost:3000 | 是 |

2. 验证脚本：

javascript复制// scripts/validate-env.js
const requiredVars = ['VITE_API_BASE_URL']

requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    throw new Error(`缺少必需环境变量: ${varName}`)
  }
})

6. 进阶：自定义环境插件开发

对于大型项目，可以开发自定义环境插件：

javascript复制// vite-plugin-env-config.js
export default function envConfigPlugin() {
  return {
    name: 'env-config',
    config(config, { mode }) {
      const env = loadEnv(mode, process.cwd())
      return {
        define: {
          __APP_ENV__: JSON.stringify({
            mode,
            ...env
          })
        }
      }
    }
  }
}

在vite.config.js中使用：

javascript复制import envConfig from './vite-plugin-env-config'

export default defineConfig({
  plugins: [envConfig()]
})

7. 实际项目经验分享

在最近的一个后台管理系统项目中，我们遇到了这样的需求：

• 开发环境使用mock数据
• 测试环境需要连接多个不同测试服务器
• 生产环境需要按地域区分API地址

最终解决方案：

1. 扩展环境模式：

json复制"scripts": {
  "dev": "vite --mode development",
  "test:server1": "vite --mode test_server1",
  "test:server2": "vite --mode test_server2",
  "build:asia": "vite build --mode production_asia",
  "build:europe": "vite build --mode production_europe"
}

2. 使用环境变量组合：

javascript复制// vite.config.js
const region = mode.includes('asia') ? 'asia' : 
  mode.includes('europe') ? 'europe' : 'default'

return {
  define: {
    __API_REGION__: JSON.stringify(region)
  }
}

3. 动态路由配置：

javascript复制// src/router/index.js
const baseUrl = import.meta.env.VITE_API_BASE_URL

if (import.meta.env.VITE_ENV === 'development') {
  router.beforeEach((to, from, next) => {
    if (to.path.startsWith('/mock')) {
      // 特殊处理mock路由
    }
    next()
  })
}

8. 现代前端工程化思考

多环境配置是前端工程化的重要环节，随着项目复杂度提升，还需要考虑：

1. 环境配置与CI/CD流水线集成
2. 环境变量与功能开关(feature flags)结合
3. 环境特定的性能监控配置
4. 环境感知的错误报告机制

一个典型的现代前端工程环境配置流程：

mermaid复制graph TD
    A[代码提交] --> B{环境判断}
    B -->|dev| C[注入开发环境变量]
    B -->|test| D[注入测试环境变量]
    B -->|prod| E[注入生产环境变量]
    C --> F[构建开发包]
    D --> G[构建测试包]
    E --> H[构建生产包]

虽然不能使用mermaid图表，但我们可以用文字描述这个流程：代码提交后，CI系统会根据目标环境注入对应的环境变量，然后执行特定环境的构建流程，最终生成针对不同环境优化的部署包。