Node.js环境变量配置实战：手把手教你构建高效、安全的开发环境

引言：为什么环境变量如此重要？

想象一下这个场景：你正在开发一个Node.js应用，需要[连接数据库]。你可能会这样写：

// ❌ 危险！不要这样做！
const dbConfig = {
    host: 'localhost',
    port: 3306,
    user: 'root',
    password: 'mysecretpassword123',
    database: 'myapp_dev'
};
AI写代码

这段代码存在几个致命问题：

1. 安全风险： 数据库密码直接暴露在代码中，一旦代码仓库（尤其是公开的GitHub）被泄露，后果不堪设想。
2. 环境耦合： 开发环境用localhost，生产环境可能用云数据库的公网IP。每次部署都要手动修改代码？
3. 协作困难： 团队成员的本地开发环境配置各不相同，如何保证每个人都能顺利运行项目？

环境变量（Environment Variables） 正是解决这些问题的"银弹"。它允许我们将配置信息与代码分离，实现：

• 安全性： 敏感信息（如密钥、密码）不进入代码仓库。
• 灵活性： 轻松在不同环境（开发、测试、生产）间切换配置。
• 可维护性： 配置集中管理，修改方便。

---

一、 基础篇：理解 process.env

在Node.js中，所有环境变量都存储在全局对象 process.env 中。这是一个类似JavaScript对象的键值对集合。

1. 查看当前环境变量

在终端中，你可以使用以下命令查看所有环境变量：

# Linux/macOS
printenv
 
# Windows
set
AI写代码

在Node.js代码中，可以这样访问：

// 查看所有环境变量
console.log(process.env);
 
// 访问特定变量
console.log(process.env.PATH); // 输出系统PATH
console.log(process.env.USER); // 输出当前用户名
AI写代码

2. 在运行时设置环境变量

最简单的方法是在启动Node.js应用时，通过命令行前缀设置：

# Linux/macOS
PORT=3000 NODE_ENV=development node app.js
 
# Windows (cmd)
set PORT=3000 && set NODE_ENV=development && node app.js
 
# Windows (PowerShell)
$env:PORT=3000; $env:NODE_ENV="development"; node app.js
AI写代码

然后在 app.js 中：

const PORT = process.env.PORT || 3000; // 如果没有设置PORT，则使用默认值3000
const NODE_ENV = process.env.NODE_ENV || 'development';
 
console.log(`Server running on port ${PORT} in ${NODE_ENV} mode`);
AI写代码

小贴士： NODE_ENV 是一个非常重要的环境变量，许多库（如Express）会根据它的值调整行为（例如，生产环境会关闭详细错误信息）。

---

二、 进阶篇：使用 dotenv 库实现配置文件化

每次启动都要手动输入环境变量，显然不现实。dotenv 库可以让我们将环境变量存储在 .env 文件中，启动时自动加载。

1. 安装与初始化

npm install dotenv
AI写代码

2. 创建 .env 文件

在项目根目录创建 .env 文件：

# .env - 开发环境配置
PORT=3000
NODE_ENV=development
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=mysecretpassword123
DB_NAME=myapp_dev
API_KEY=sk_test_1234567890abcdef
AI写代码

3. 加载 dotenv

在应用的最开始 （通常是 app.js 或 server.js 的第一行）引入并配置 dotenv：

// app.js
require('dotenv').config(); // ⚠️ 必须是第一行！
 
const express = require('express');
const app = express();
 
const PORT = process.env.PORT || 3000;
const NODE_ENV = process.env.NODE_ENV;
 
// ... 其他代码
AI写代码

重要： dotenv.config() 必须在任何使用 process.env 的代码之前执行。

4. 多环境配置：.env.development, .env.production

为了更好地管理不同环境，我们可以创建多个 .env 文件：

• .env (通用配置，可被覆盖)
• .env.local (本地覆盖，通常不提交到Git)
• .env.development (开发环境)
• .env.test (测试环境)
• .env.production (生产环境)

dotenv 会根据 NODE_ENV 的值自动加载对应的文件。例如：

# 启动开发环境
NODE_ENV=development node app.js # 会加载 .env 和 .env.development
 
# 启动生产环境
NODE_ENV=production node app.js # 会加载 .env 和 .env.production
AI写代码

.env.development 示例：

# .env.development
NODE_ENV=development
PORT=3000
DB_HOST=localhost
DB_NAME=myapp_dev
# 开发环境可能不需要密码，或使用简单密码
DB_PASSWORD=devpass
AI写代码

.env.production 示例：

# .env.production
NODE_ENV=production
PORT=8080
DB_HOST=prod-db.myapp.com
DB_NAME=myapp_prod
# 生产环境密码必须复杂，且不应出现在代码中
DB_PASSWORD=${DB_PROD_PASSWORD} # 使用系统环境变量
AI写代码

---

三、 实战：构建一个健壮的配置管理模块

硬编码\] `process.env.XXX` 在多处使用，既不优雅也容易出错。我们来创建一个专门的配置模块。 #### [](https://link.juejin.cn?target= "")1. 创建 `config/index.js` ```kotlin // config/index.js require('dotenv').config(); class Config { constructor() { this.port = this.get('PORT', 3000); this.nodeEnv = this.get('NODE_ENV', 'development'); this.isProduction = this.nodeEnv === 'production'; this.isDevelopment = this.nodeEnv === 'development'; this.isTest = this.nodeEnv === 'test'; this.db = { host: this.get('DB_HOST', 'localhost'), port: this.get('DB_PORT', 3306), user: this.get('DB_USER'), password: this.get('DB_PASSWORD'), database: this.get('DB_NAME') }; this.api = { key: this.get('API_KEY') }; // 验证必要配置 this.validate(); } /** * 获取环境变量，支持默认值 * @param {string} key - 环境变量键 * @param {*} defaultValue - 默认值 * @returns {*} */ get(key, defaultValue = undefined) { return process.env[key] || defaultValue; } /** * 验证必要配置是否存在 */ validate() { const required = ['DB_USER', 'DB_PASSWORD', 'DB_NAME', 'API_KEY']; const missing = []; required.forEach(key => { if (!process.env[key]) { missing.push(key); } }); if (missing.length > 0) { throw new Error(`Missing required environment variables: ${missing.join(', ')}`); } } } // 创建单例 const config = new Config(); module.exports = config; AI写代码 ``` #### [](https://link.juejin.cn?target= "")2. 在应用中使用 ```ini // app.js const config = require('./config'); const express = require('express'); const app = express(); app.listen(config.port, () => { console.log(`Server running on port ${config.port} in ${config.nodeEnv} mode`); }); // 连接数据库示例 // const mysql = require('mysql2'); // const connection = mysql.createConnection(config.db); AI写代码 ``` **优势：** * **集中管理：** 所有配置在一个地方。 * **类型安全（部分）：** 提供默认值，避免 `undefined` 错误。 * **验证：** 启动时检查必要配置，防止运行时崩溃。 * **语义化：** `config.db.host` 比 `process.env.DB_HOST` 更清晰。 *** ** * ** *** ### [](https://link.juejin.cn?target= "")四、 安全与最佳实践 #### [](https://link.juejin.cn?target= "")1. `.gitignore` 是你的第一道防线 **绝对不要** 将包含敏感信息的 `.env` 文件提交到版本控制系统！ 在 `.gitignore` 文件中添加： ```bash # Environment variables .env .env.local .env.*.local *.env AI写代码 ``` 只提交一个 `.env.example` 作为模板： ```ini # .env.example - Copy this to .env and fill in your values PORT=3000 NODE_ENV=development DB_HOST=localhost DB_PORT=3306 DB_USER= DB_PASSWORD= DB_NAME= API_KEY= AI写代码 ``` 新成员只需复制 `.env.example` 为 `.env` 并填写自己的值。 #### [](https://link.juejin.cn?target= "")2. 生产环境：永远不要依赖 `.env` 文件 在生产服务器上，**不要** 使用 `.env` 文件。应该通过以下方式设置环境变量： * **操作系统级：** 在服务器的 `~/.bashrc`, `/etc/environment` 中设置。 * **容器化 (Docker)：** 在 `docker run` 命令或 `docker-compose.yml` 中使用 `environment` 字段。 ```ini # docker-compose.yml services: app: image: myapp:latest environment: - NODE_ENV=production - PORT=8080 - DB_HOST=prod-db - DB_PASSWORD=${DB_PASSWORD} # 从主机环境或Secret读取 AI写代码 ``` * **PaaS平台 (如Heroku, Vercel)：** 在平台的控制台中设置环境变量。 * **CI/CD管道：** 在Jenkins、GitHub Actions等工具中配置Secrets。 #### [](https://link.juejin.cn?target= "")3. 使用 `cross-env` 解决跨平台兼容性 如果你在Windows和Linux/macOS上开发，`cross-env` 可以让你用统一的命令设置环境变量。 ```lua npm install --save-dev cross-env # package.json { "scripts": { "dev": "cross-env NODE_ENV=development node app.js", "start": "cross-env NODE_ENV=production node app.js" } } AI写代码 ``` #### [](https://link.juejin.cn?target= "")4. 避免在客户端暴露敏感信息 如果使用Next.js、Nuxt.js等同构框架，注意： * 以 `NEXT_PUBLIC_` 开头的环境变量会被暴露到前端。 * 敏感信息（如数据库密码、API密钥）**绝不能** 以 `NEXT_PUBLIC_` 开头。 *** ** * ** *** ### [](https://link.juejin.cn?target= "")五、 高级技巧：动态配置与CI/CD集成 #### [](https://link.juejin.cn?target= "")1. 动态加载配置 有时配置需要根据运行时条件动态生成： ```kotlin // config/index.js // ... this.redisUrl = this.isProduction ? `redis://:${process.env.REDIS_PASSWORD}@prod-redis:6379` : 'redis://localhost:6379'; // ... AI写代码 ``` #### [](https://link.juejin.cn?target= "")2. CI/CD中的环境变量 在GitHub Actions中使用Secrets： ```yaml # .github/workflows/deploy.yml jobs: deploy: steps: - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies run: npm ci - name: Run tests env: NODE_ENV: test DB_PASSWORD: ${{ secrets.DB_TEST_PASSWORD }} run: npm test - name: Deploy to Production if: github.ref == 'refs/heads/main' run: | # 部署命令，使用生产环境变量 NODE_ENV=production DB_PASSWORD=${{ secrets.DB_PROD_PASSWORD }} npm run deploy env: DB_PASSWORD: ${{ secrets.DB_PROD_PASSWORD }} AI写代码 ``` *** ** * ** *** ### [](https://link.juejin.cn?target= "")六、 总结 通过本文的系统学习，你应该已经掌握了Node.js环境变量配置的核心技能： 1. **基础：** 理解 `process.env` 和命令行设置。 2. **核心：** 使用 `dotenv` 库和 `.env` 文件实现配置文件化。 3. **进阶：** 创建健壮的配置模块，实现集中管理与验证。 4. **安全：** 通过 `.gitignore` 保护敏感信息，生产环境使用系统级变量。 5. **实践：** 将环境变量无缝集成到Docker、CI/CD等现代开发流程中。 **记住：** 良好的配置管理是构建专业、可维护、安全的Node.js应用的基石。不要再让硬编码的密码和混乱的配置拖慢你的开发效率了！