React 项目环境变量使用指南

在 React 项目中正确使用环境变量是管理不同环境配置的关键技术。以下是完整的解决方案：

1. 创建环境变量文件

React 项目支持以下环境变量文件（按优先级从高到低）：

• .env.development.local (本地开发环境)
• .env.development (开发环境)
• .env.production.local (生产环境本地覆盖)
• .env.production (生产环境)
• .env (所有环境)

示例文件内容

# .env.development
REACT_APP_API_URL=https://dev.api.example.com
REACT_APP_DEBUG=true

# .env.production
REACT_APP_API_URL=https://api.example.com
REACT_APP_DEBUG=false

2. 环境变量命名规则

必须以 REACT_APP_ 开头，否则 React 不会包含它：

# 正确 ✅
REACT_APP_API_KEY=abc123

# 错误 ❌（不会被包含）
API_KEY=abc123

3. 在代码中访问环境变量

// 直接通过 process.env 访问
const apiUrl = process.env.REACT_APP_API_URL;

function App() {
  return (
    <div>
      <p>API 地址: {process.env.REACT_APP_API_URL}</p>
      {process.env.REACT_APP_DEBUG && <DebugPanel />}
    </div>
  );
}

4. 不同环境的构建命令

Create React App 自动根据命令使用对应环境文件：

# 开发环境（使用 .env.development）
npm start

# 生产环境（使用 .env.production）
npm run build

# 测试环境（使用 .env.test）
npm test

5. 自定义环境配置

如果需要更多环境（如 staging）：

1. 安装 env-cmd：

npm install env-cmd

2. 创建 .env.staging 文件

3. 修改 package.json：

{
  "scripts": {
    "build:staging": "env-cmd -f .env.staging npm run build"
  }
}

6. TypeScript 支持

在 src/react-env.d.ts 中添加类型声明：

declare namespace NodeJS {
  interface ProcessEnv {
    REACT_APP_API_URL: string;
    REACT_APP_DEBUG?: 'true' | 'false';
    // 添加其他环境变量...
  }
}

7. 高级用法

动态配置

// src/config.js
const config = {
  apiUrl: process.env.REACT_APP_API_URL,
  debug: process.env.REACT_APP_DEBUG === 'true',
  // 其他配置...
};

export default config;

在 HTML 中使用

<title>%REACT_APP_SITE_NAME%</title>

8. 安全注意事项

1. 不要在前端代码中存储敏感信息（如数据库密码）
2. 不要将 .env.local 提交到版本控制
3. 生产环境变量应通过 CI/CD 系统设置

9. 常见问题解决

问题1：环境变量未生效

• 确保变量名以 REACT_APP_ 开头
• 重启开发服务器（npm start）
• 检查 .gitignore 是否包含 .env.local

问题2：TypeScript 报错

添加或更新 src/react-env.d.ts 类型声明文件

问题3：构建后变量不更新

• 生产环境变量是在构建时嵌入的，需要重新构建
• 对于运行时配置，考虑使用 public/config.js 动态加载

10. 替代方案比较

通过遵循这些实践，您可以有效地管理 React 项目中的环境变量，确保不同环境间的配置隔离和安全。