Nodejs多环境配置方案学习笔记

核心知识点

1. dotenv 配置方案

1.1 什么是 dotenv？

dotenv 是一个在 Node.js 环境中广泛使用的配置管理库，用于解析 .env 文件中的环境变量，并将其挂载到 process.env 对象上。

周下载量：非常高，说明应用广泛
最新版本：16.x，相对稳定

1.2 安装与基础使用

bash

npm install dotenv

创建 .env 文件（项目根目录）：

code

TOKEN_SECRET=your_long_random_secret
USERNAME=example_user
PASSWORD=my_super_secret_password

Common JS 写法：

javascript

// index.js
require('dotenv').config();

console.log(process.env.TOKEN_SECRET);
console.log(process.env.USERNAME);
console.log(process.env.PASSWORD);

ES6 写法：

javascript

import 'dotenv/config';
// 或
import dotenv from 'dotenv';
dotenv.config();

console.log(process.env.TOKEN_SECRET);

1.3 嵌套数据的处理

.env 文件不支持嵌套结构，需要使用前缀命名：

code

DATABASE_USERNAME=admin
DATABASE_PASSWORD=secret123
SITE_DATABASE_HOST=localhost
SITE_DATABASE_PORT=5432

缺点：配置项多时，命名会变得很长，查找不方便。

1.4 使用场景

简单配置场景
需要兼容前后端统一配置
项目发布到线上时，在同级目录创建 .env 文件避免环境差异问题

2. config 配置方案

2.1 什么是 config？

config 是 Node.js 环境下读取配置文件的库，支持 YAML、JSON 等多种格式，提供强大的多环境配置合并功能。

支持格式：JSON、YAML、XML、CSV 等
核心功能：自动合并不同环境的配置

2.2 安装与基础使用

bash

npm install config
# 如需支持 YAML 格式，还需要安装 js-yaml
npm install js-yaml

创建配置文件目录结构：

code

config/
├── default.json      # 默认配置
├── development.json  # 开发环境配置
└── production.json   # 生产环境配置

配置文件示例（config/default.json）：

json

{
  "token": {
    "secret": "your_long_secret"
  },
  "db": {
    "host": "localhost",
    "port": 5432,
    "username": "test",
    "password": "example"
  }
}

代码中使用：

javascript

const config = require('config');

// 读取嵌套配置
const dbConfig = config.get('db');

console.log(dbConfig.host);      // localhost
console.log(dbConfig.port);     // 5432

2.3 多环境配置合并

创建开发环境配置（config/development.json）：

json

{
  "db": {
    "host": "localhost",
    "port": 5432
  }
}

创建生产环境配置（config/production.json）：

json

{
  "db": {
    "host": "your-domain.com",
    "port": 55432
  }
}

设置环境变量并运行：

bash

# Linux/Mac
export NODE_ENV=production
node index.js

# Windows (PowerShell)
$env:NODE_ENV="production"
node index.js

# 或使用 cross-env 跨平台
npm install cross-env

执行后，config 会自动合并 default.json 和当前环境配置，当前环境配置会覆盖默认配置。

2.4 YAML 格式支持

需要安装 js-yaml：

bash

npm install js-yaml

YAML 格式示例（config/default.yaml）：

yaml

token:
  secret: your_long_secret

db:
  host: localhost
  port: 5432
  username: test
  password: example

2.5 配合 dotenv 使用

bash

npm install dotenv cross-env

在 package.json 中配置脚本：

json

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development node index.js",
    "prod": "cross-env NODE_ENV=production node index.js"
  }
}

3. 两种方案对比

特性	dotenv	config
支持格式	`.env` 纯文本	JSON、YAML 等多种格式
数据结构	扁平化，不支持嵌套	支持嵌套结构
多环境	需手动指定文件	自动合并多环境配置
使用方式	`process.env.XXX`	`config.get('xxx')`
适用场景	简单配置	复杂多环境项目

选型建议

场景	推荐方案
简单配置，变量较少	dotenv
复杂嵌套配置	config
多环境（dev/prod/test）自动切换	config
前后端统一配置	dotenv

代码实战案例

需求描述

构建一个支持多环境的数据库配置系统，能够根据 NODE_ENV 自动切换开发和生产环境配置。

完整实现

项目结构：

code

myapp/
├── config/
│   ├── default.json
│   ├── development.json
│   └── production.json
├── .env
├── index.js
└── package.json

第一步：安装依赖

bash

npm init -y
npm install dotenv config cross-env

第二步：创建配置文件

config/default.json：

json

{
  "db": {
    "host": "localhost",
    "port": 5432,
    "username": "root",
    "password": "root"
  },
  "app": {
    "name": "MyApp",
    "version": "1.0.0"
  }
}

config/development.json：

json

{
  "db": {
    "host": "localhost",
    "port": 5432
  }
}

config/production.json：

json

{
  "db": {
    "host": "prod-db.example.com",
    "port": 55432,
    "username": "prod_user",
    "password": "secure_password"
  }
}

第三步：创建入口文件

javascript

// index.js
require('dotenv').config();
const config = require('config');

// 获取数据库配置
const dbConfig = config.get('db');

// 获取应用配置
const appConfig = config.get('app');

console.log('='.repeat(50));
console.log(`应用名称: ${appConfig.name}`);
console.log(`应用版本: ${appConfig.version}`);
console.log('='.repeat(50));
console.log('数据库配置:');
console.log(`  主机: ${dbConfig.host}`);
console.log(`  端口: ${dbConfig.port}`);
console.log(`  用户名: ${dbConfig.username}`);
console.log(`  密码: ${dbConfig.password}`);
console.log('='.repeat(50));

第四步：配置运行脚本

package.json：

json

{
  "scripts": {
    "dev": "cross-env NODE_ENV=development node index.js",
    "prod": "cross-env NODE_ENV=production node index.js",
    "start": "node index.js"
  }
}

运行结果

开发环境 (npm run dev)：

code

==================================================
应用名称: MyApp
应用版本: 1.0.0
==================================================
数据库配置:
  主机: localhost
  端口: 5432
  用户名: root
  密码: root
==================================================

生产环境 (npm run prod)：

code

==================================================
应用名称: MyApp
应用版本: 1.0.0
==================================================
数据库配置:
  主机: prod-db.example.com
  端口: 55432
  用户名: prod_user
  密码: secure_password
==================================================

常见问题与解决方案

问题	原因	解决方案
YAML 格式解析失败	未安装 `js-yaml`	`npm install js-yaml`
Windows 无法设置环境变量	命令不兼容	使用 `cross-env` 或 `set` 命令
配置读取为 undefined	`NODE_ENV` 未设置或配置文件名不匹配	检查环境变量和文件名对应关系
dotenv 读取不到变量	`.env` 文件位置不对	确保 `.env` 在项目根目录
config 合并不生效	环境配置文件名不正确	确认文件名与 `NODE_ENV` 对应

学习要点总结

dotenv 适用于简单配置场景，通过 .env 文件管理扁平化的键值对
config 支持嵌套结构和多环境自动合并，适合复杂项目
多环境配置的核心是 NODE_ENV 环境变量的设置与识别
cross-env 解决跨平台设置环境变量的问题
生产环境中敏感信息（如数据库密码）不应提交到代码仓库，应使用 .gitignore 忽略

延伸学习资源

官方文档

最佳实践

生产环境配置使用环境变量注入，避免硬编码
.env 文件应加入 .gitignore
使用 config 库时，默认配置放 default.json，环境差异放对应环境文件

进阶话题

配置加密与安全存储
远程配置中心（Apollo、Nacos）
12-Factor App 配置管理原则