环境变量管理

工程化规范中的环境变量管理

环境变量管理是前端工程化中不可忽视的一环。合理的环境变量配置能提升团队协作效率，降低环境差异导致的bug，同时保障敏感信息的安全性。随着项目复杂度增加，环境变量管理需要系统化的解决方案。

环境变量的核心作用

环境变量主要用于区分不同运行环境（开发、测试、生产等）的配置参数。典型场景包括：

• API基础路径
• 第三方SDK密钥
• 功能开关
• 日志级别
• 性能监控配置

// 传统硬编码方式的弊端
const API_URL = 'https://api.prod.example.com' 

// 环境变量方式
const API_URL = process.env.API_BASE_URL

硬编码方式需要每次部署时手动修改代码，而环境变量通过外部注入实现动态配置。

常见环境变量管理方案

1. .env 文件方案

现代前端框架普遍支持.env文件管理：

# .env.development
VUE_APP_API_URL=https://api.dev.example.com
VUE_APP_DEBUG=true

# .env.production  
VUE_APP_API_URL=https://api.example.com
VUE_APP_DEBUG=false

Create React App和Vue CLI等工具链会自动根据NODE_ENV加载对应文件：

// React中使用
console.log(process.env.REACT_APP_API_URL) 

// Vue中使用
console.log(process.env.VUE_APP_DEBUG)

2. 构建时注入方案

Webpack等构建工具支持环境变量注入：

// webpack.config.js
const webpack = require('webpack')

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.API_KEY': JSON.stringify(process.env.API_KEY)
    })
  ]
}

3. 运行时加载方案

对于需要动态配置的场景，可采用异步加载方式：

// config.js
export async function loadConfig() {
  const response = await fetch('/config.json')
  window.__APP_CONFIG__ = await response.json()
}

// 组件中使用
const apiUrl = window.__APP_CONFIG__.API_URL

工程化最佳实践

类型安全的环境变量

使用TypeScript定义环境变量类型：

// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    readonly REACT_APP_API_URL: string
    readonly REACT_APP_ENV: 'development' | 'production'
    readonly REACT_APP_VERSION: string
  }
}

多环境管理策略

建议采用三级环境划分：

1. 开发环境（development）
2. 预发布环境（staging）
3. 生产环境（production）

对应目录结构：

config/
  ├── .env.development
  ├── .env.staging
  └── .env.production

敏感信息防护

禁止在前端直接暴露敏感信息：

# 错误示例
VUE_APP_DB_PASSWORD=123456

# 正确做法
VUE_APP_API_ENDPOINT=/api

敏感信息应通过后端接口动态获取或使用加密方案。

高级应用场景

微前端环境隔离

在微前端架构中，需要处理环境变量冲突：

// 主应用加载子应用时注入环境变量
window.loadMicroApp('sub-app', {
  env: {
    API_PREFIX: '/sub-api'
  }
})

测试环境Mock

结合环境变量实现自动化测试Mock：

// jest.config.js
process.env = {
  ...process.env,
  API_MOCK: 'true'
}

// api.test.js
if (process.env.API_MOCK) {
  jest.mock('../api')
}

常见问题解决方案

环境变量未生效排查

1. 检查变量命名是否符合框架要求（如Vue需要VUE_APP_前缀）
2. 确认.env文件放置位置正确
3. 重启开发服务器（部分工具需要重启才能加载新变量）

跨平台兼容处理

处理Windows和Unix环境差异：

// 统一路径处理
const configPath = path.join(
  process.env.HOME || process.env.USERPROFILE,
  '.app_config'
)

大型项目优化方案

对于包含数百个环境变量的项目：

1. 按功能模块拆分.env文件
2. 使用env-cmd工具按需加载
3. 建立环境变量文档中心

# 使用env-cmd加载特定文件
env-cmd -f .env.feature_x npm start

工具链集成方案

Docker集成示例

FROM node:16

ARG API_BASE_URL
ENV REACT_APP_API_URL=$API_BASE_URL

COPY . .
RUN npm build

构建时注入变量：

docker build --build-arg API_BASE_URL=https://api.example.com .

CI/CD管道配置

GitLab CI示例：

deploy_prod:
  stage: deploy
  script:
    - echo "VUE_APP_VERSION=$CI_COMMIT_TAG" >> .env
    - npm run build
  only:
    - tags

浏览器兼容性处理

处理旧浏览器环境变量支持：

// 兼容IE11的polyfill
if (!window.process) {
  window.process = { env: {} }
}

监控与告警机制

建立环境变量健康检查：

// 启动时校验必要变量
const requiredVars = ['API_URL', 'AUTH_DOMAIN']
requiredVars.forEach(varName => {
  if (!process.env[varName]) {
    console.error(`Missing required env var: ${varName}`)
  }
})

性能优化方向

1. 避免在业务代码中频繁访问process.env
2. 构建时将常量内联
3. 使用Tree-shaking移除无用变量

// 优化前
function getConfig() {
  return {
    debug: process.env.DEBUG === 'true'
  }
}

// 优化后（通过babel插件转换）
function getConfig() {
  return {
    debug: false // 构建时替换
  }
}