聊聊前端容易翻车的“环境管理”

想获取更多2025年最新前端场景题可以看这里 ：fe.ecool.fun

大家好，我是刘布斯。

周末在家整理以前的老硬盘，翻到了 10 年前做的一个外包项目源码。打开一看，入口文件里赫然写着一行被注释掉的代码：

auto 复制代码

// var API_HOST = "http://localhost:8080"; var API_HOST = "http://192.168.1.100:8080"; // 只有内网能访问

看到这行代码，那种被"发布上线后页面一片白屏"支配的恐惧瞬间攻击了我。

入行十几年，前端工程化变了好几轮，但"环境管理"这个问题，反而是很多团队（甚至大厂内部的小组）最容易翻车的地方。今天不讲什么高大上的微前端或 Serverless，单纯聊聊在 Dev、Test、UAT、Prod 这一堆环境里打滚摸出来的路子。

最早那会，根本没有 process.env。

那时候发版简直是玄学。周五晚上要上线，整个流程大概是这样的：我在本地把 API 地址改成线上的，Ctrl+S 保存，然后用 FTP 传到服务器。

最要命的不是忘了改地址，而是改错了没改回来。

我有次在生产环境调试一个 bug，顺手把 URL 改成了测试环境的模拟接口，验证完觉得没问题，就直接关机下班......结果第二天客服群炸了，老板当时看我的眼神，感觉已经在琢磨开除我对项目有没有影响了。

这个阶段的痛苦在于：代码和配置不分家。代码逻辑是同一套，但因为环境不同，竟然需要每次手动去改源码。这本身就是个巨大的风险源。

后来构建工具起来了，Webpack 简直是救世主。

大家开始习惯用 DefinePlugin，或者后来的 dotenv。在根目录下建几个文件：.env.development，.env.production。

auto 复制代码

// webpack.config.js
new webpack.DefinePlugin({
  'process.env.API_URL': JSON.stringify('https://api.prod.com')
})

这时候最常见的一个坑是：以为写了 process.env 就万事大吉了。

记得有次带新人，小伙子把阿里云的 OSS AccessKeySecret 直接写到了 .env 文件里，并且还被 Webpack 打包进了 bundle.js。

他觉得 .env 在服务器上，很安全。但他忘了前端代码是跑在用户浏览器里的。我随手打开 Chrome 控制台，切到 Network 面板，搜一下源码，那个 Key 就赤裸裸地躺在那儿。

从那以后，我在 Code Review 里加了一条铁律：凡是打进前端包里的变量，默认就是公开的。 涉及私密的配置，一律要在 Nginx 层或者 BFF 层（Node.js 中间件）处理，绝对不能进 Webpack。

这几年容器化成了标配，问题又升级了。

用 .env 文件最大的问题是：配置是构建时（Build-time）注入的。

测试那边的老哥不止一次跟我抱怨："你们前端真麻烦，我这只是想把测试环境的镜像推到预发环境验证一下，结果因为 API 地址变了，我还得重新跑一遍 npm run build？这镜像还能叫不可变交付吗？"

这确实是个硬伤。理想的 Docker 流程是：镜像 build 出来后，这是一个死的包。我在测试环境跑它，它连测试库；我在生产环境跑它，它连生产库。镜像本身不应该变，变的是启动容器时传进去的环境变量。

如果用 Webpack 把 API 地址写死在 JS 里，这镜像就废了，只能在那一个环境用。

为了解决这个问题，也为了少被测试大佬的抱怨，我们现在的很多项目都切到了运行时注入的方案。

原理其实也很简单，就是"回光返照"到了 jQuery 时代：把配置挂在 window 上。

核心逻辑就这两步：

代码里不读 process.env ：前端代码里所有需要区分环境的地方，全部改成读取 window.__APP_CONFIG__.API_URL。
HTML 模板里留个坑 ：在 index.html 的 <head> 里，放一个空的 script 标签，或者特殊的占位符。
容器启动时填坑 ：这是最关键的一步。容器启动的时候（或者 Nginx 启动时），通过写一个简单的 Shell 脚本，去读取机器的环境变量，然后生成一个 config.js 文件，内容就是：
auto 复制代码
```
window.__APP_CONFIG__ = {
  API_URL: "https://api.real-prod.com",
  THEME_COLOR: "blue"
};
```
然后把这个文件塞进 Nginx 的静态资源目录里。

这样一来，前端打出来的包是完全干净的，不带任何环境信息。镜像推到哪里，只要那个环境的 Docker 启动参数配对了，页面就能正常跑。

auto 复制代码

# docker-compose 示例
environment:
  - API_URL=https://api.staging.com

这个方案不仅解决了"一次构建"的问题，还有一个隐藏的好处：回滚极快。

以前发版如果配置错了，要重新打包发布，起码 10 分钟。现在只要改一下容器的环境变量重启一下，30 秒搞定。对于那种高压力的线上故障修复，这几分钟就是命。

最后再唠叨几个细节，都是踩坑踩出来的：

不要信任 .gitignore：总有人会手抖把 .env.local 提交上去。我们在 CI/CD 流程里加了扫描，一旦发现这就没法 merge。
版本号要在控制台打印出来 ：每次打包，我会把当前的 git commit hash 和打包时间注入到 window 对象里，并在 console 里打印出来。
以前测试提 bug，我问"是最新版吗？"，对方说"是"。结果查半天是缓存。
现在我让他们截图控制台，我看一眼 hash 也就知道是不是最新版，省了太多扯皮时间。
Feature Flag 也可以用环境配置：不要傻傻地用注释代码的方式来开关功能，而是直接把它做成配置项。万一上线后这功能有 bug，改个配置就能关掉，不用重新发版，这在在大促期间简直是保命符。

环境管理看着不起眼，也没什么高深的算法，但它决定了一个团队开发的"下限"。

下限越稳，大家才越敢在上面折腾新东西。毕竟，谁也不想半夜三点爬起来因为少改了一个 URL 而回滚代码，对吧？

如果你觉得现在的项目构建太慢，或者经常因为环境配置问题和各方大佬扯皮，可以去检查一下构建脚本，是不是还在针对每个环境单独打包？

如果是，试着把那部分配置抽离出来，哪怕先不用 Docker，先试着写一个 config.js 加载一下，你会发现世界瞬间清静了很多。