中大型 Web 项目必看：把 NODE_ENV 和 APP_ENV 彻底分开

大家好，今天想和大家讨论和分享一下我对 web 项目里 NODE_ENV 环境变量的看法。

前言

在很多 web 项目里，环境变量的设计往往是一个“看起来简单，但实际非常容易踩坑”的问题。

最典型的就是：

NODE_ENV 到底应该怎么用？ dev / test / staging / prod 要不要塞进 NODE_ENV？

这几年来我经历过各种大小草台班子，接手过各种 web 项目，看到很多团队图省事，会把所有环境都塞进 NODE_ENV，比如：

NODE_ENV=dev 
NODE_ENV=test 
NODE_ENV=uat
NODE_ENV=staging
NODE_ENV=prod

这种方式前期看似乎没问题，但随着项目变复杂，需求、环境变多，参与人数变多等等，这种设计基本都会逐渐变成隐患。

今天分享这篇文章，主要想和大家分享一下，我们得搞清楚一下几点：

• NODE_ENV 的本质是什么？
• 为什么不能把它当环境枚举
• 运行时变量应该如何设计
• 推荐的实践方案

NODE_ENV 的本质：运行模式

NODE_ENV 是 运行模式。

很多测试框架会强制设 NODE_ENV=test

当我们在项目里需要判定当前逻辑所处的运行模式是什么的时候，记住：在 Web 开发中， NODE_ENV 其实有着非常明确的约定：

很多框架和库都会根据 NODE_ENV 自动设定一些行为，比如：

• 是否输出详细错误信息
• 是否开启调试日志
• 是否启用性能优化
• 是否使用缓存
• 是否压缩资源

如果你把 NODE_ENV 改成：

NODE_ENV=uat
NODE_ENV=staging

这些库很可能识别不了，从而导致行为异常。

概念误区： 把 NODE_ENV 当环境名

我曾经把 NODE_ENV 当成”当前代码运行在哪一个环节“的判定依据：

if (process.env.NODE_ENV === 'dev') {} 
if (process.env.NODE_ENV === 'uat') {} 
if (process.env.NODE_ENV === 'staging') {}

这里其实混淆了两个基本概念：

• 运行模式 - mode
  • 是否开启调试：development 开启，production 关闭
  • 是否压缩日志：development 关闭，production 开启
• 部署环境 - environment
  • dev 开发环境
  • test 测试环境
  • prod 生产环境

或许我们不应该用同一个变量来表示这两种概念。

对吧？运行模式的关注点在于代码如何运行，我们根据这一点来控制是否调试、是否输出细节，启用 source map，运行模式会影响打包结果，并且应该进入构建产物内部，我不在乎这份代码构建后在什么环境下运行。

然而部署环境就不一样了，它的核心关注点是：代码运行在哪里？

举个例子，假设代码运行在 test 环境下，我们正在对代码进行测试，难道这时候你想要让类似 Sentry 这样的第三方服务接入进来吗？

当然不需要！就算是免费的服务，也不需要在测试的时候接进来啊，白嫖也不行！

我们需要用一个变量来标识部署的环境，也可以说是运行的环境。

但现实是很多团队、项目会一把梭 NODE_ENV，某种意义上来说，这个变量传播最早也最广，大家习惯了用它控制一切。

并且，一个变量就能决定“开发时友好，生产时高效”，确实方便。

但我们不能忽略这样做的代价：

• 语义不清晰：NODE_ENV=production 时，到底是“打包成生产模式”还是“当前部署在生产环境”？经常说不清。
• 无法灵活组合：我想在 test 环境也用 production mode（为了测性能、测构建产物），或者在 prod 环境临时开启 development mode 调试问题，就很尴尬。
• 配置爆炸：很多人最后搞出 development, test, staging, production 四种模式，却又在里面嵌套各种 feature flags，配置越来越乱。

推荐做法：NODE_ENV + APP_ENV

在前端项目中，NODE_ENV 主要影响构建结果（Vite/Webpack）；在后端（如 Node.js/NestJS/Express）中，更建议用 APP_ENV 控制业务配置。

NODE_ENV：只保留给构建工具使用（vite/rollup 等），严格只有 development / production 两个值。

APP_ENV 或 DEPLOY_ENV：真正代表部署环境（dev/test/staging/prod）。

举个例子：一个电商系统的 Staging 环境

Staging 环境的定位：

• 目的是在上线前做最接近真实生产的完整测试（包括性能、功能、集成）。
• 通常由 QA、产品、运维一起验证，模拟真实用户流量。
• 核心需求：行为要和生产环境几乎一致，但数据和外部服务是隔离的。

如果不分开（只用一个变量，比如 NODE_ENV 或 ENV），可能有人会这样写：

# 很多人会这么写
ENV=staging
# 或者
NODE_ENV=staging

然后代码里这样判断：

if (process.env.NODE_ENV === 'production') {
  // 生产行为：压缩、关闭调试、无彩色日志等
} else {
  // 开发行为：详细日志
  // source map、React DevTools 等
}

在 staging 环境下会出现以下问题：

想用 production mode 的优化，但环境变量是 staging。

结果是用了 development 模式：代码没压缩、日志超级详细、source map 没去掉、性能比生产差很多，无法准确验证性能和稳 定性。

想用 development mode 方便调试，但又怕污染生产行为。

如果强行设 NODE_ENV=development，那整个 staging 就失去了“类生产”的意义，测出来的结果不可信。

配置冲突：数据库要用 staging 专属的库（不能连 prod DB） 支付、短信、推送等第三方服务要用测试账号，但日志、监控、告警又希望和生产保持一致（格式、级别、压缩方式）

最终结果：要么 staging 测不准，要么调试很便秘，花费的时间大大增加，然后？导致加班 ？🤣

现在就以这个为例，我们试试看拆开成两个变量：

# 运行模式（决定代码如何运行、打包结果）
NODE_ENV=production        
# 或 APP_MODE=production

# 部署环境（决定连哪个数据库、用什么密钥、开哪些功能）   
# dev | test | staging | prod
APP_ENV=staging       

其他场景下，NODE_ENV 基本都设置为 production！部署环境则根据 test、staging、prod 来切换逻辑。

在这个 Staging 环境下，运行模式是 production，构建后：

• 代码是压缩的、tree-shaking 后的
• 肯定没有 source map
• 日志是结构化的，压缩的，不至于打印多余的彩色日志，详细堆栈也不会暴露
• 框架的开发警告全部关闭
• 性能和生产环境一致

同时，部署环境是 staging：

• 根据部署环境连接 staging 数据库（当然也可以在 CI 的时候专门注入数据库链接）
• 测试支付渠道走的是沙箱
• 独立的 staging 域名、监控 Tag、开放的功能

代码示例：

const mode = process.env.NODE_ENV;        // production
const env  = process.env.APP_ENV;         // staging

// 构建/运行时行为
const isProdMode = mode === 'production';

// 业务和基础设施配置
const config = {
  db: {
    host: env === 'prod' ? 'prod-db' : `${env}-db`,
  },
  logging: {
    level: isProdMode ? 'info' : 'debug',
    pretty: !isProdMode,
  },
  features: featureFlags[env],   // staging 可以有独立的 feature flags
};

甚至配置文件也可以按 APP_ENV 拆分：

• .env.local
• .env.dev
• .env.test
• .env.staging
• .env.prod

这样一来我们就可以去做一次性构建，多环境部署。

在 CI/CD 的过程中，只需要构建一次代码，再部署到多个环境即可。多环境下多次重复构建就显得有点浪费时间了。

写进 README 的规范

以下几点，我将之写入了自己所有项目的 README 中

• NODE_ENV 只允许：development / test / production
• APP_ENV 用于区分部署环境：local / dev / test / staging / prod
• 除本地开发和自动化测试外，所有服务运行在 NODE_ENV=production
• 禁止使用 NODE_ENV 判断 dev/test/staging/prod
• 所有环境差异统一通过 APP_ENV + 配置文件管理

如果你正在做一个中大型后端系统，这一条设计，值得你在一开始就定对。否则后面重构成本会非常高。

如果你已经在用 NODE_ENV=dev/staging/prod，也可以逐步引入 APP_ENV，把职责拆清楚，就能平滑过渡。

最后

最近 AI 的发展实在是太快了，很多人已经完全不再编写代码，Vibe coding 堪比许愿，在 Agent 帮助下，连自己review 都省了。

但是，我还是觉得 AI 只是拓展开发者能力的工具，至少目前还是！我们可以借助 AI 来做很多原本自身做不到的事情，或者需要花很多时间精力才能做到的事情。但是在开发这件事情上，一切的根基还是我们自己。

感谢大家看到这里，如果你喜欢我分享的内容，欢迎给我三连支持，你的支持是我更新下去的动力！

下次见，Bye 👋🏻