React / 系统课时
管理环境变量
管理环境变量
前端项目经常要在开发、测试和生产之间切换 API 地址或功能开关。本篇以 Vite 为例建立一套可落地的环境变量约定,并说明哪些值可以进入浏览器、哪些绝不能放进前端构建产物。
学习目标
- 使用不同
.env文件区分开发与生产配置 - 在 React 代码中读取 Vite 暴露的环境变量
- 识别前端环境变量的安全边界,避免把密钥打进浏览器包
按运行模式拆分配置
Vite 会按 mode 加载对应环境文件。开发模式常用 .env.development,生产构建常用 .env.production;只有以 VITE_ 开头的自定义变量会暴露给客户端代码。
# .env.development
VITE_API_BASE_URL=http://localhost:3000
VITE_FEATURE_BETA=true
# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_FEATURE_BETA=false这两个文件生效后的行为是:开发模式读取本地 API 地址和开启的功能开关,生产构建读取生产 API 地址并关闭该开关。验证时应分别启动开发模式和生成生产构建,确认页面读取到的值符合当前 mode。
在 React 中集中读取并校验
不要在几十个组件里直接散落 import.meta.env。把读取、默认值和类型转换集中到一个配置模块,错误会更早暴露,也更容易测试。
// 只从 Vite 暴露的客户端变量中读取公开配置。
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
// 环境变量是字符串,布尔值需要显式转换。
const betaEnabled = import.meta.env.VITE_FEATURE_BETA === 'true';
if (!apiBaseUrl) {
throw new Error('VITE_API_BASE_URL is required');
}
export default function App() {
return (
<main>
<p>API: {apiBaseUrl}</p>
<p>Beta: {betaEnabled ? 'enabled' : 'disabled'}</p>
</main>
);
}预期结果:开发模式页面应显示开发文件中的 API 地址,并把 Beta 显示为 enabled;生产构建则应显示生产地址和 disabled。
Development: API=http://localhost:3000, Beta=enabled
Production: API=https://api.example.com, Beta=disabled如果配置缺少 VITE_API_BASE_URL,应用会在模块加载阶段直接抛错,比请求发出后才出现模糊的网络错误更容易定位。
理解环境变量的安全边界
前端环境变量不是服务器密钥仓库。任何被 VITE_ 暴露并在代码中引用的值,都可能进入最终 JavaScript 包,用户可以通过浏览器开发者工具或下载静态资源查看。
因此,API 公共地址、公开功能开关、非敏感版本号可以放在前端环境变量中;数据库密码、私钥、第三方服务的服务端密钥、长期访问令牌则必须留在服务端。即使把敏感值写进 .env.local 并加入 .gitignore,只要变量被打包进客户端,它仍然会泄露给最终用户。
让团队配置可复制
仓库可以提交不含敏感值的 .env.example,明确项目需要哪些变量;真实环境文件按团队策略忽略或由部署平台注入。部署时应把“构建阶段变量”和“运行时服务器变量”区分开,因为 Vite 的客户端变量通常在构建时被替换。
对 React 前端而言,最重要的规则很简单:把环境变量当作“不同环境下的公开配置”,而不是“隐藏秘密的地方”。需要保密的值应由后端代为使用,再通过受控接口把必要结果返回给浏览器。