🎯 场景说明
假设你正在开发一个 React 应用，需要调用后端 API，而 API 的地址在不同的环境下是不一样的，比如：
开发环境（development）：http://localhost:8080/api
测试环境（staging）：https://staging.api.example.com/api
生产环境（production）：https://api.example.com/api
为了避免在代码中硬编码这些 URL，我们使用 环境变量 来管理它们，这样可以根据当前环境自动切换对应的配置。
✅ 一、环境变量基础规则（Create React App 项目）
如果你使用的是 Vite 创建的 React 项目，规则略有不同，我也会在最后补充说明。
1. 环境变量文件命名规范（CRA）
在 Create React App (CRA) 项目中，环境变量必须以 REACT_APP_开头，否则 React 无法在代码中访问它们。
可用的环境变量文件有：
| 文件名 | 用途 | 加载时机 |
|---|---|---|
.env |
默认，所有环境共用 | 始终加载 |
.env.development |
开发环境（npm start） | 开发时加载 |
.env.production |
生产环境（npm run build） | 构建时加载 |
.env.test |
测试环境（npm test） | 测试时加载 |
⚠️ 注意：文件应该放在 项目根目录（和 package.json 同级）
二、项目文件结构示例
my-react-app/
├── public/
├── src/
│ ├── App.js
│ └── ...
├── .env <-- 所有环境默认加载（可选）
├── .env.development <-- 开发环境专用
├── .env.production <-- 生产环境专用
├── package.json
└── ...🔧 三、创建环境变量文件
-
.env.development（开发环境）
.env.development
REACT_APP_API_URL=http://localhost:8080/api
REACT_APP_ENV=development -
.env.production（生产环境）
.env.production
REACT_APP_API_URL=https://api.example.com/api
REACT_APP_ENV=production你可以根据需要添加更多变量，比如：
REACT_APP_AUTH_DOMAIN
REACT_APP_GOOGLE_MAPS_KEY
等等
🚨 所有自定义环境变量必须以 REACT_APP_开头！
🧠 四、React 代码中使用环境变量
示例：在 API 请求或配置中使用
// src/utils/api.js
const apiUrl = process.env.REACT_APP_API_URL;
const env = process.env.REACT_APP_ENV;
console.log('当前环境:', env); // development / production
console.log('API Base URL:', apiUrl);
// 模拟一个 API 请求函数
export async function fetchUsers() {
try {
const response = await fetch(`${apiUrl}/users`);
if (!response.ok) {
throw new Error('网络请求失败');
}
const data = await response.json();
return data;
} catch (error) {
console.error('获取用户失败:', error);
throw error;
}
}在组件中使用：
// src/App.js
import React, { useEffect, useState } from 'react';
import { fetchUsers } from './utils/api';
function App() {
const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function loadData() {
try {
const data = await fetchUsers();
setUsers(data);
} catch (err) {
console.error(err);
} finally {
setLoading(false);
}
}
loadData();
}, []);
if (loading) return <div>加载中...</div>;
return (
<div>
<h1>用户列表（当前环境：{process.env.REACT_APP_ENV}）</h1>
<ul>
{users.map((user) => (
<li key={user.id}>{user.name}</li>
))}
</ul>
</div>
);
}
export default App;▶️ 五、运行与构建命令
-
启动开发服务器（自动使用 .env.development）
npm start
此时 React 会自动加载 .env.development中的变量，例如：
REACT_APP_API_URL=http://localhost:8080/api-
构建生产版本（自动使用 .env.production）
npm run build
此时会使用 .env.production中的变量，例如：
REACT_APP_API_URL=https://api.example.com/api⚠️ 注意：npm run build生成的是静态文件，环境变量会被打包进去，运行时无法动态修改！
🧪 六、其他环境（如测试环境）
如果你有测试环境，可以创建一个 .env.test文件：
# .env.test
REACT_APP_API_URL=https://test.api.example.com/api
REACT_APP_ENV=test并在运行测试时确保使用该文件（通常测试框架如 Jest 会自动处理）。
🛠 七、Vite 项目中的环境变量（补充）
如果你没有使用 Create React App，而是使用 Vite + React（比如通过 npm create vite@latest创建的项目），环境变量的规则稍有不同：
命名规则：
所有自定义环境变量需要以 VITE_ 开头，而不是 REACT_APP_。
文件名：
- .env
- .env.development
- .env.production
- .env.test
代码中使用：
const apiUrl = import.meta.env.VITE_API_URL;而不是：
// ❌ CRA 才用这个
process.env.REACT_APP_API_URL示例（Vite + React）：
# .env.development
VITE_API_URL=http://localhost:8080/api
VITE_ENV=development
// src/api.js
const apiUrl = import.meta.env.VITE_API_URL;
console.log(apiUrl); // http://localhost:8080/api✅ 总结：环境变量使用完整流程
| 步骤 | 操作内容 |
|---|---|
| 1️⃣ | 在项目根目录创建 .env.development和 .env.production文件 |
| 2️⃣ | 定义以 REACT_APP_开头的自定义变量（CRA）或 VITE_（Vite） |
| 3️⃣ | 在代码中通过 process.env.REACT_APP_XXX（CRA）或 import.meta.env.VITE_XXX（Vite）访问 |
| 4️⃣ | 运行 npm start使用开发环境变量，npm run build使用生产环境变量 |
| 5️⃣ | 可根据需要创建 .env.test或其它自定义环境配置 |
📌 最佳实践建议
- 不要将敏感信息（如私钥、密码）放入前端环境变量中，因为它们会被打包并暴露给客户端！
- 合理划分环境，比如 dev / staging / prod，分别管理对应 API 和功能开关。
- 使用 .env管理配置常量，而不是硬编码在代码中，便于维护和多环境部署。
- 团队协作时，将 .env.example提交到 Git，里面包含变量名但不含敏感值，提醒团队成员创建自己的 .env文件。