Node.js环境变量加载问题解析与解决方案

1. Node.js 环境变量加载问题深度解析

今天在开发Node.js后端项目时，遇到了一个看似简单却困扰了我好几个小时的环境变量加载问题。这个问题表面上看是.env文件读取失败，但背后涉及到Node.js模块加载机制、工作目录理解和环境变量加载顺序等多个技术点。下面我将详细记录这个问题的发现、分析和解决过程，希望能帮助遇到类似问题的开发者少走弯路。

1.1 问题现象描述

我在开发一个使用Oracle数据库的Node.js后端服务时，编写了数据库连接测试脚本db.test.js和配置文件config.js。测试时发现，当我在不同目录下执行这些脚本时，环境变量的加载结果完全不同。

具体表现为：

• 在项目根目录（backend/nodejs）下执行脚本时，能正确读取.env文件中的配置
• 进入src/config或src/data子目录执行相同脚本时，所有环境变量都变成undefined
• 只有设置了默认值的配置项（如port）能正常工作

1.2 环境变量加载机制剖析

要理解这个问题，我们需要深入分析dotenv的工作原理和Node.js的模块系统：

1. dotenv.config()的默认行为：

   • 默认会在process.cwd()（即当前工作目录）下查找.env文件
   • 不会向上级目录递归查找
   • 加载后会将变量注入到process.env对象中

2. Node.js模块解析规则：

   • 模块内的相对路径是相对于当前模块所在目录解析的
   • 但环境变量加载与模块路径无关，只与进程工作目录有关

3. 环境变量加载顺序：

   • 系统环境变量
   • .env文件中的变量（通过dotenv加载）
   • 运行时传入的参数
   • 后加载的会覆盖先加载的值

2. 问题根源与解决方案

2.1 根本原因定位

通过分析，问题的核心在于工作目录(working directory)与项目结构不匹配。当我们在子目录中执行脚本时，process.cwd()变成了子目录路径，而dotenv只在当前工作目录下查找.env文件，导致加载失败。

具体来说：

• 项目结构：

  code复制backend/nodejs/
    ├── .env
    ├── src/
        ├── config/
        │   └── config.js
        └── data/
            └── db.test.js
  

• 在nodejs目录执行时，process.cwd()是/path/to/backend/nodejs，能找到.env
• 在src/config目录执行时，process.cwd()是/path/to/backend/nodejs/src/config，找不到.env

2.2 解决方案比较

经过实践验证，有几种可行的解决方案：

方案1：统一从项目根目录执行脚本（推荐）

bash复制# 无论脚本在哪个子目录，都从项目根目录执行
node ./src/config/config.js
node ./src/data/db.test.js

优点：

• 无需修改代码
• 符合Node.js项目常规实践
• 各种工具（如npm scripts）默认也是这种工作方式

方案2：在代码中指定.env路径

修改config.js，显式指定.env文件路径：

javascript复制import dotenv from 'dotenv';
import path from 'path';
import { fileURLToPath } from 'url';

// 获取当前模块的绝对路径
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// 计算.env文件的绝对路径
dotenv.config({
  path: path.resolve(__dirname, '../../../.env')
});

优点：

• 可以在任何目录下执行脚本
• 路径解析更