React 项目环境变量使用指南-EW帮帮网

在 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）：

安装 env-cmd：

npm install env-cmd

创建 .env.staging 文件
修改 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. 安全注意事项

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

9. 常见问题解决

问题1：环境变量未生效

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

问题2：TypeScript 报错

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

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

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

10. 替代方案比较

方案	优点	缺点
传统 .env 文件	简单直接	需要重新构建才能更新
运行时加载配置	无需重新构建	增加初始加载时间
后端接口获取配置	动态更新	需要额外API调用

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

React 项目环境变量使用指南