React / 系统课时

管理环境变量

管理环境变量

前端项目经常要在开发、测试和生产之间切换 API 地址或功能开关。本篇以 Vite 为例建立一套可落地的环境变量约定,并说明哪些值可以进入浏览器、哪些绝不能放进前端构建产物。

学习目标

  • 使用不同 .env 文件区分开发与生产配置
  • 在 React 代码中读取 Vite 暴露的环境变量
  • 识别前端环境变量的安全边界,避免把密钥打进浏览器包

按运行模式拆分配置

Vite 会按 mode 加载对应环境文件。开发模式常用 .env.development,生产构建常用 .env.production;只有以 VITE_ 开头的自定义变量会暴露给客户端代码。

text
# .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。把读取、默认值和类型转换集中到一个配置模块,错误会更早暴露,也更容易测试。

jsx
// 只从 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。

text
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 前端而言,最重要的规则很简单:把环境变量当作“不同环境下的公开配置”,而不是“隐藏秘密的地方”。需要保密的值应由后端代为使用,再通过受控接口把必要结果返回给浏览器。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理环境变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通