环境变量Environment Variable

切环境不改代码，密钥永远不进仓库

在 dev / staging / production 三个标签间切换，看同一份代码读出完全不同的配置；再把 API_KEY 写进代码并提交，看 git 历史立刻翻成危险态、部署被挡下。

面板教会的事

把刚才操作里出现的因果关系，提炼成可复述的几条。

• 配置随环境切换：DATABASE_URL、LOG_LEVEL、错误堆栈、FEATURE_BILLING 的值都来自环境变量；切 dev / prod 时代码一行没改。
• 同一份构建跑遍三环境：dev → staging → production 是配置升级阶梯，构建产物不变，只换注入的值。
• NODE_ENV 还会翻转运行时行为：生产压住错误堆栈、开启压缩与缓存，开发放开详细日志——这同样由环境决定。
• 密钥绝不进 git：API_KEY 写进代码 = 进入 git 历史，删文件也抹不掉，必须轮换；正确做法是 secrets 管理器注入，仓库只留 .env.example。

什么时候用

出现这些信号，先怀疑环境，而不是先改代码。

• 「本地能跑、上生产就报错」——多半是环境之间漂移：数据不同、配置不同、规模不同。
• 同一个 bug 只在生产复现——先逐项比对环境变量，而不是急着改代码。
• 想给预发布单独开新功能、暂关生产——用 FEATURE_* 环境变量，而不是另开一条分支。

环境不是万能分身：如果两个环境的行为差异大到要走不同代码路径，那是配置没收敛，而不是再多开一个环境。

怎么用

从写代码到部署的最短路径。

1. 代码里只读 process.env.DATABASE_URL 这类变量名，不写任何具体值。
2. 仓库提交 .env.example，只列变量名和格式；.env 写进 .gitignore。
3. 本机用 .env.local，部署平台用 secrets 管理器按 dev / staging / prod 注入。
4. 启动时校验必需变量，缺失就立刻失败、只列出变量名（不回显值），别等第一次请求才返回含糊 500。
5. 部署后核对当前环境读到的是对的值（DB 连接、日志级别、功能开关），再宣布上线。

正反例：同一份代码，只改密钥放哪

差异只在「密钥进不进仓库」这一处。