Node.js 生产环境最佳实践：正确设置 NODE_ENV=production 的完整指南

本文是开源仓库 nodebestpractices「生产环境（Production）」章节的核心实践之一（对应主 README.md 中的 5.15 条目），围绕 NODE_ENV 环境变量的由来、设置与读取方法、性能与安全影响展开，并结合仓库中的代码示例与关联实践给出可落地的生产配置方案。读完本文，你将掌握如何在不同部署环境中注入 NODE_ENV=production、理解它为何能显著提升 Express 等框架的吞吐量，以及它在错误处理与日志诊断中扮演的关键角色。

NODE_ENV 是什么：进程环境变量与 Node 的约定

进程环境变量（process environment variables）是一组以键值对形式提供给任何运行中程序的配置数据。虽然你可以使用任意自定义变量，Node 社区鼓励遵循一个约定：使用名为 NODE_ENV 的变量来标记「当前是否处于生产环境」。

这个判定结果至关重要——它允许框架和组件在开发阶段提供更好的诊断能力，例如禁用缓存或输出冗长的日志语句；而在生产阶段则切换到优化模式。换言之，NODE_ENV 是连接「开发体验」与「生产性能」之间的一把开关。

所有现代部署工具——Chef、Puppet、CloudFormation 等——都支持在部署时设置环境变量，这意味着你完全可以在不修改代码的前提下，由部署流水线来决定应用以哪种模式运行。

代码实例：设置与读取 NODE_ENV

原文档给出了最基础、也最经典的两种操作：启动进程前在 bash 中设置变量，以及在代码中读取变量。

方式一：启动 Node 进程前在 bash 中设置

// Setting environment variables in bash before starting the node process
$ NODE_ENV=development
$ node

这里 NODE_ENV=development 是 bash 中常见的变量赋值写法。实际部署时，更常用的是将赋值与启动命令合并为一条，使其仅对当前命令生效：

$ NODE_ENV=production node server.js

若希望变量对当前 shell 会话内后续所有命令生效，可以使用 export NODE_ENV=production。无论哪种方式，关键点在于：变量必须在 Node 进程启动之前注入，因为进程一旦启动，其环境快照就已经固化。

方式二：使用代码读取环境变量

// Reading the environment variable using code
if (process.env.NODE_ENV === 'production')
    useCaching = true;

process.env 是 Node.js 暴露进程环境变量的全局对象。上面的写法通过严格相等判断当前模式，进而决定是否启用缓存。更稳健的工程写法是把它抽取成一个布尔常量，避免在代码中到处重复判断：

const isProduction = process.env.NODE_ENV === 'production';

if (isProduction) {
  useCaching = true;
  // 启用压缩、关闭调试日志等生产优化
}

值得强调的是：当 NODE_ENV 未设置时，许多框架（如 Express）会默认按 development 模式处理——这正是下面要展开的性能隐患的根源。

为什么必须设置：性能影响与框架行为

主仓库 README.md 对这条实践给出了精炼的 TL;DR：

TL;DR: 将环境变量 NODE_ENV 设为 production 或 development，用于标记是否激活生产优化——部分 npm 包会据此判断当前环境，并为生产环境优化其代码。

否则（Otherwise）： 遗漏这一简单属性，可能会在使用 Express 服务端渲染等特定库时大幅降低性能。

来自 Dynatrace 博客的基准数据

原文档引用了 Dynatrace 博客的实测结论（原引文）：

……在 Node.js 中存在一个使用 NODE_ENV 变量设置当前运行模式的约定。我们看到它实际上会读取 NODE_ENV，如果该变量未设置，则默认取值为 development。我们清晰地看到：将 NODE_ENV 设为 production 后，Node.js 能够处理的请求数量提升约三分之二，同时 CPU 使用率甚至略有下降。让我强调一下：将 NODE_ENV 设为 production 能让你的应用快 3 倍！

这一结论的机制并不神秘：当框架按 development 模式运行时，会开启详尽的日志、未优化的模板渲染、开发辅助功能等开销；切到 production 后这些开销被关闭或替换为生产级实现，从而释放吞吐能力。

来自 Snyk 博客的补充说明

英文原版文档 sections/production/setnodeenv.md 还引用了 Snyk 博客的补充观点：

……只有当 NODE_ENV 环境变量被设为 production 时，某些框架和库才会启用适合生产环境的优化配置。暂且不论这种设计的好坏，了解这一点至关重要。

这提醒我们：是否设置 NODE_ENV 不仅影响你自己的代码，更影响你依赖的第三方库的代码路径。

安全维度：生产模式下错误细节不再泄露

NODE_ENV 的影响远不止性能。仓库 sections/security/hideerrors.md 明确指出：Express 自带内置错误处理器，位于中间件栈的末尾；当你在自定义错误处理器中未处理而将错误传给 next() 时，内置处理器会接手——当 NODE_ENV 为 development 时，堆栈跟踪（stack trace）会直接写给客户端；而当 NODE_ENV 为 production 时，只返回 HTTP 状态码，不再泄露堆栈信息。

也就是说，NODE_ENV=production 同时是生产环境信息泄露防护的一道天然屏障，避免攻击者通过堆栈信息反推服务端文件路径、第三方模块与内部工作流。

如何在不同部署环境中设置 NODE_ENV

1. 命令行 / CI 流水线

$ NODE_ENV=production node server.js

2. 部署工具

原文档明确提到，Chef、Puppet、CloudFormation 等现代部署工具都支持在部署阶段设置环境变量。你可以把 NODE_ENV 的赋值放在部署配方、配置模板或编排定义中，而不是写死在代码里——这样同一份代码可以无差别地在开发、预发、生产环境间流转。

3. 容器化部署（Docker）

在 Docker 场景下，可以在 Dockerfile 中通过 ENV NODE_ENV=production 固化到镜像，或在运行时用 docker run -e NODE_ENV=production 注入。仓库的 sections/docker 小节集中讨论了生产级镜像构建、依赖安装（如 install-for-production.md）等配套实践，可与本实践组合使用。

4. 统一约定：进程级变量

无论采用哪种方式，请牢记 NODE_ENV 是进程级环境变量，必须在进程启动前完成注入；同时保持团队内部取值口径一致（production / development / test 等），避免因为大小写或取值不统一导致判断失效。

常见误区与注意事项

• 不要依赖「未设置 = 生产」：如 Dynatrace 引文所述，未设置时框架默认按 development 处理，性能与安全都会打折扣，必须显式设置。
• NODE_ENV 只承担运行模式标记职责：它是「环境类型」标识，不是存放密钥、连接串等敏感信息的场所。敏感配置应走专门的密钥管理流程，可参考仓库 sections/security/secretmanagement.md 与 sections/security/avoid_publishing_secrets.md。
• 避免在代码中写死模式：将模式交给部署环境注入，才能让同一构建产物适配不同环境，与仓库「无状态服务」（bestateless.md）等生产实践理念一致。

仓库中的延伸阅读

• 本条实践的英文原版：sections/production/setnodeenv.md，包含完整的双博客引文
• 主文档索引：README 5.15 条目（README.md）
• 与 NODE_ENV 直接相关的错误处理实践：sections/security/hideerrors.md
• 生产环境完整实践集合：见 sections/production 目录（如 LTS 版本选用 LTSrelease.md、事务 ID 日志 assigntransactionid.md 等）

一句话总结：NODE_ENV=production 是投入产出比最高的生产配置之一——一行环境变量，换来的是框架级优化、显著吞吐提升与错误细节防护三重收益。