Node.js 环境变量管理与多环境配置实践

# Node.js 环境变量管理与多环境配置实践 ## 前言 数据库密码、API 密钥这些不能写死在代码里，必须通过环境变量注入。但环境变量怎么管理、多环境怎么区分，很多项目做得混乱。本文梳理一套规范的实践。 ## 为什么用环境变量 - 敏感信息（密码、密钥）不入库 - 不同环境（开发/测试/生产）配置不同 - 部署时无需改代码 - 符合 12-Factor App 规范 ## 基础：process.env ```javascript // 读取环境变量 const port = process.env.PORT || 3000; const dbHost = process.env.DB_HOST || "localhost"; console.log(`服务运行在 ${port} 端口`); ``` ```bash # 启动时设置环境变量 PORT=8080 node app.js # Windows PowerShell $env:PORT=8080; node app.js ``` ## dotenv 加载 .env 文件 ```bash npm install dotenv ``` ```javascript // 在入口文件最顶部加载 require("dotenv").config(); // 或指定文件 require("dotenv").config({ path: ".env.production" }); ``` ```bash # .env 文件 DB_HOST=localhost DB_PORT=5432 DB_PASSWORD=secret123 API_KEY=xxx ``` 注意：`.env` 文件要加入 `.gitignore`，不能提交到仓库。 ## 多环境配置 ```bash # 项目结构 .env # 默认配置（开发） .env.test # 测试环境 .env.production # 生产环境 .env.example # 配置模板（提交到仓库） ``` ```javascript // 根据 NODE_ENV 加载不同配置 const env = process.env.NODE_ENV || "development"; require("dotenv").config({ path: `.env.${env}` }); // 或统一在 config.js 里管理 const config = { development: { db: "mongodb://localhost:27017/dev", }, production: { db: process.env.PROD_DB_URL, }, }; module.exports = config[process.env.NODE_ENV || "development"]; ``` ## 敏感信息管理 ### 加密密钥放哪 - 本地开发：`.env` 文件 - 服务器：环境变量（systemd、Docker env） - 云平台：密钥管理服务（AWS Secrets Manager、KMS） ### Docker 环境变量 ```bash docker run -e DB_PASSWORD=secret -e API_KEY=xxx my-app # 或用 env 文件 docker run --env-file .env.production my-app ``` ### systemd 环境变量 ```ini [Service] Environment=NODE_ENV=production Environment=DB_PASSWORD=secret ``` ## 配置校验 启动时校验必填配置，避免运行时才发现缺失： ```javascript const required = ["DB_HOST", "DB_PASSWORD", "API_KEY"]; for (const key of required) { if (!process.env[key]) { console.error(`缺少必需的环境变量: ${key}`); process.exit(1); } } ``` 或用 envalid 库做类型校验。 ## 常见踩坑 ### 坑1：.env 提交到仓库 ```bash # .gitignore .env .env.* !.env.example ``` ### 坑2：dotenv 加载顺序 `dotenv.config()` 必须在读取环境变量的代码之前执行，通常放入口文件第一行。 ### 坑3：process.env 全是字符串 ```javascript // process.env.PORT 是字符串，需要转换 const port = parseInt(process.env.PORT, 10); const debug = process.env.DEBUG === "true"; ``` ### 坑4：修改 .env 后不生效 环境变量只在进程启动时读取，改了 .env 要重启服务。 ## 小结 环境变量管理的要点：敏感信息不硬编码、用 dotenv 加载 .env、按 NODE_ENV 区分多环境、启动时校验必填项。`.env` 一定加 gitignore，`.env.example` 提供模板方便协作。