3. 配置管理与环境隔离

在 Node.js 服务端工程中，配置管理是连接代码与运行环境的桥梁。同一份代码在开发机上连接本地数据库、在测试环境连接测试库、在生产环境连接主库，还要区分日志级别、第三方密钥、限流阈值等差异。如果把这些差异硬编码进源码，就会导致“改一处、发一次版”的脆弱流程，也极易把生产密钥提交到 Git 仓库。本节围绕 dotenv、config、环境变量与多环境配置文件，讲清如何实现配置注入、环境隔离与启动期校验。

一、配置的三种来源与优先级

Node.js 中配置通常来自三个层次：进程环境变量（process.env）、配置文件（如 config/default.json）、代码默认值。合理的优先级是：环境变量 > 环境专属配置文件 > 默认配置文件 > 代码兜底。这样在容器化部署时，运维只需注入环境变量即可覆盖镜像内的默认配置，无需重新构建镜像。

dotenv 的职责是把 .env 文件中的键值对加载进 process.env，它只负责“注入”，不负责“校验”和“分层”。因此它通常放在应用入口最顶部执行：

// src/bootstrap.js
require('dotenv').config({ path: `.env.${process.env.NODE_ENV || 'development'}` });

注意 dotenv 默认不会覆盖已存在的环境变量，这正好符合“环境变量优先”的原则。生产环境一般通过 K8s Secret、Docker --env-file 或 CI 变量注入，而不是把 .env.production 提交到仓库。

二、用 config 包实现多环境分层

config 包（node-config）在 dotenv 之上提供了目录化的分层能力。典型目录结构如下：

config/
  default.json        # 所有环境共享的默认值
  development.json    # 开发环境覆盖
  test.json           # 测试环境覆盖
  production.json     # 生产环境覆盖
  custom-environment-variables.json  # 环境变量映射

其中 custom-environment-variables.json 是敏感信息注入的关键，它把环境变量名映射到配置路径：

{
  "db": {
    "password": "DB_PASSWORD",
    "host": "DB_HOST"
  },
  "jwt": {
    "secret": "JWT_SECRET"
  }
}

这样代码里始终写 config.get('db.password')，而真实值由运行环境注入。开发时在 .env.development 中写 DB_PASSWORD=dev123，生产则由密钥管理系统提供，代码零改动。

三、环境隔离的边界与常见陷阱

环境隔离不只是“换数据库地址”，还包括：日志级别（开发 debug、生产 info）、错误堆栈是否外露、缓存与队列地址、第三方沙箱与正式网关、限流与超时参数。建议在 default.json 中只放与安全无关的默认值，把密钥、连接串、开关全部下沉到环境变量或环境专属文件。

常见陷阱有三类：一是 NODE_ENV 未设置导致加载了错误的配置文件；二是 .env 被误提交，应在 .gitignore 中排除 .env* 并保留 .env.example 作为字段说明；三是配置读取散落在各处，难以审计。推荐在启动阶段集中读取一次，冻结为不可变对象再注入各模块。

四、启动期配置校验：把错误挡在进程之外

配置错误最怕“启动成功、运行到某条路径才崩”。解决办法是在启动阶段用 Schema 校验。以 joi 为例：

const Joi = require('joi');
const schema = Joi.object({
  NODE_ENV: Joi.string().valid('development','test','production').required(),
  PORT: Joi.number().port().default(3000),
  DB_HOST: Joi.string().hostname().required(),
  DB_PASSWORD: Joi.string().min(8).required(),
  JWT_SECRET: Joi.string().min(32).required(),
  LOG_LEVEL: Joi.string().valid('debug','info','warn','error').default('info')
}).unknown(true);

const { error, value } = schema.validate(process.env, { abortEarly: false });
if (error) {
  console.error('[config] 校验失败:', error.details.map(d => d.message).join('; '));
  process.exit(1);
}

校验通过后，把 value 冻结并导出，业务代码只依赖这个对象，不再直接读 process.env。这样既统一了入口，也便于测试时替换。

五、可执行的配置清单示例

下面是一份可直接参考的配置字段表，覆盖开发、测试、生产三套环境的差异点。示例值仅用于说明，实际部署时请替换为真实值。

六、小结与落地建议

配置管理的核心是“分层 + 注入 + 校验”。dotenv 负责把本地文件注入环境变量，config 负责按环境合并配置树，Schema 校验负责在启动期拦截缺失或非法值。三者组合后，代码只依赖一份冻结的配置对象，环境差异全部外置。落地时建议：入口文件第一行加载 dotenv；用 custom-environment-variables.json 映射敏感项；启动时执行一次校验并 fail-fast；把 .env* 加入 .gitignore，只保留 .env.example。这样既保证了开发效率，也守住了生产安全边界。