不告诉别人关键配置（“这个环境变量必须设，但我不说”）

环境变量在前端项目中的隐秘性

前端项目里经常需要处理敏感信息或关键配置，比如API密钥、数据库连接字符串、第三方服务凭证等。这些信息绝对不能直接硬编码在代码中提交到版本控制系统。环境变量成为解决这个问题的标准方案，但团队协作时经常遇到"这个环境变量必须设，但我不说"的情况。

为什么环境变量需要保密

假设有个React项目需要调用天气API，代码可能是这样的：

// 错误示范：直接硬编码API密钥
const fetchWeather = async (city) => {
  const response = await fetch(
    `https://api.weatherapi.com/v1/forecast.json?key=123abc&q=${city}`
  );
  return response.json();
};

这种写法至少有三大问题：

1. API密钥直接暴露在代码仓库中
2. 所有开发者都能看到生产环境的密钥
3. 密钥变更需要修改代码并重新部署

正确的环境变量使用方法

现代前端框架通常都支持环境变量。以Create React App为例：

1. 创建.env文件：

REACT_APP_WEATHER_API_KEY=123abc

2. 修改代码：

const fetchWeather = async (city) => {
  const response = await fetch(
    `https://api.weatherapi.com/v1/forecast.json?key=${process.env.REACT_APP_WEATHER_API_KEY}&q=${city}`
  );
  return response.json();
};

3. 将.env加入.gitignore：

# .gitignore
.env
.env.local

团队协作时的环境变量管理

当新人加入项目时，经常会遇到"项目跑不起来，因为缺少环境变量"的情况。以下是几种解决方案：

方案一：提供.env.example文件

# .env.example
REACT_APP_WEATHER_API_KEY=your_api_key_here
REACT_APP_BASE_URL=https://api.example.com

这个文件应该提交到版本控制，实际值由团队成员自行补充。

方案二：使用加密的环境变量

对于CI/CD环境，可以使用平台提供的加密环境变量功能。比如GitHub Actions：

# .github/workflows/deploy.yml
env:
  REACT_APP_WEATHER_API_KEY: ${{ secrets.WEATHER_API_KEY }}

方案三：本地开发时自动提示

可以在应用启动时检查必要环境变量：

// src/utils/envCheck.js
const requiredEnvVars = [
  'REACT_APP_WEATHER_API_KEY',
  'REACT_APP_BASE_URL'
];

export const checkEnv = () => {
  const missingVars = requiredEnvVars.filter(varName => !process.env[varName]);
  if (missingVars.length > 0) {
    console.error(`缺少必要的环境变量: ${missingVars.join(', ')}`);
    console.info('请参考.env.example文件配置');
    process.exit(1);
  }
};

然后在应用入口调用：

import { checkEnv } from './utils/envCheck';
checkEnv();

环境变量的进阶用法

类型安全的环境变量

在TypeScript项目中，可以定义环境变量的类型：

// src/env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    readonly REACT_APP_WEATHER_API_KEY: string;
    readonly REACT_APP_BASE_URL: string;
    readonly REACT_APP_ENV: 'development' | 'production' | 'test';
  }
}

环境变量转换

有时需要将环境变量转换为特定类型：

const config = {
  apiKey: process.env.REACT_APP_WEATHER_API_KEY,
  debug: process.env.REACT_APP_DEBUG === 'true',
  maxRetries: parseInt(process.env.REACT_APP_MAX_RETRIES || '3')
};

多环境管理

可以创建多个环境文件：

• .env.development - 开发环境
• .env.test - 测试环境
• .env.production - 生产环境

框架会根据NODE_ENV自动加载对应的文件。

常见的环境变量陷阱

1. 前端环境变量的安全性：记住前端环境变量仍然会被打包到客户端代码中，不适合存储真正的敏感信息。对于高度敏感的信息，应该通过后端服务中转。

2. 命名冲突：不同库可能使用相同的环境变量名，比如API_KEY这种通用名称。应该使用项目前缀，如REACT_APP_。

3. 缓存问题：修改环境变量后可能需要清除缓存或重启开发服务器才能生效。

4. 大小写问题：某些系统对环境变量名大小写敏感，最好统一使用大写。

5. 字符串引号：在.env文件中，值通常不需要引号，除非包含空格或特殊字符：

# 正确
REACT_APP_NAME=My App
REACT_APP_DESCRIPTION="An application for weather"

# 错误
REACT_APP_NAME="My App"

自动化工具推荐

1. dotenv - 最流行的环境变量加载库
2. env-cmd - 支持从特定文件加载环境变量
3. cross-env - 跨平台设置环境变量
4. vault - 企业级密钥管理工具

安装示例：

npm install dotenv env-cmd cross-env --save-dev

使用示例：

// package.json
{
  "scripts": {
    "start": "env-cmd -f .env.development react-scripts start",
    "build:prod": "env-cmd -f .env.production react-scripts build"
  }
}

环境变量的测试策略

在测试中管理环境变量也很重要：

// jest.config.js
module.exports = {
  setupFiles: ['<rootDir>/tests/setupEnv.js']
};

// tests/setupEnv.js
process.env.REACT_APP_TEST_MODE = 'true';
process.env.REACT_APP_API_URL = 'http://test.api.example.com';

或者在测试文件中直接设置：

describe('Weather API', () => {
  beforeAll(() => {
    process.env.REACT_APP_WEATHER_API_KEY = 'test_key';
  });

  it('should fetch weather data', async () => {
    // 测试代码
  });
});

环境变量与前端架构

在大型前端项目中，环境变量的管理可以更加结构化：

1. 创建专门的配置模块：

// src/config/index.js
const config = {
  api: {
    baseUrl: process.env.REACT_APP_BASE_URL,
    key: process.env.REACT_APP_API_KEY,
    timeout: parseInt(process.env.REACT_APP_API_TIMEOUT || '5000')
  },
  features: {
    analytics: process.env.REACT_APP_FEATURE_ANALYTICS === 'true',
    experimental: process.env.REACT_APP_FEATURE_EXPERIMENTAL === 'true'
  }
};

export default config;

2. 在整个应用中统一使用这个配置模块，而不是直接访问process.env。

3. 可以为不同环境创建不同的配置工厂：

// src/config/factory.js
const developmentConfig = {
  api: {
    baseUrl: 'http://localhost:3000'
  }
};

const productionConfig = {
  api: {
    baseUrl: 'https://api.example.com'
  }
};

export const getConfig = () => {
  switch(process.env.REACT_APP_ENV) {
    case 'production':
      return productionConfig;
    default:
      return developmentConfig;
  }
};