Node.js21ESM模块中加载dotenv读取环境变量

在 Node.js 21 环境下使用 ECMAScript 模块（即 ESM 规范，通过 import 语法加载依赖）时，直接调用 dotenv.config() 常常无法按预期将 .env 文件中的变量注入后续模块。这一现象的核心根源在于 ESM 规范中的“静态导入提升（Hoisting）”机制。本文将直接说明该问题的内在成因，给出三种工业级解决方案，并深入探讨 Node.js 21 原生提供的命令行环境变量加载新特性。

一、为什么 ESM 模式下的 dotenv 容易失效？

在传统的 CommonJS 模式下，代码是按顺序同步执行的，开发者习惯于先调用 require('dotenv').config()，再 require('./database.js')，此时数据库模块内部完全能通过 process.env 读取到已载入的配置。

但在 ESM 模式（在 package.json 中声明 "type": "module"）下，规范强制规定所有顶层的 import 声明必须在模块评估执行之前完成解析与依赖绑定。这意味着：即便将 dotenv.config() 写在两行 import 之间，JavaScript 引擎也会先执行所有被静态导入的模块，最后才开始运行模块主体中的函数调用。

// ❌ 常见失效写法：index.js
import dotenv from 'dotenv';
dotenv.config(); // 这一行并不会在下面的 import 之前生效！
import { connectDB } from './db.js';

connectDB(); // db.js 内部读取 process.env.DB_HOST 时值为 undefined

当 db.js 内部初始化连接池时，process.env 尚未注入 .env 文件内容，导致应用在启动瞬间就因配置缺失而崩溃。

二、Node.js 21 中使用 dotenv 的三种标准方案

为了让 dotenv 在 ESM 规范下正确生效，必须确保环境变量在任何依赖它们的业务模块被求值之前注入。以下是三种经过充分验证的标准实践。

方案 1：置顶导入 dotenv/config 副作用

这是最简洁且无需更改启动命令的代码级方案。dotenv 提供了一个专门的子路径 dotenv/config，该模块一旦被加载就会自动调用一次内部的 config() 方法。

// index.js
import 'dotenv/config'; // 必须放在所有其他业务 import 的最顶端！
import { connectDB } from './db.js';

console.log('读取到的服务端口:', process.env.PORT);
connectDB();

ESM 规范规定，同一个模块内部的静态导入按书写顺序从上往下依次求值。因此将 import 'dotenv/config' 放在第一行，可以保证它先于 import { connectDB } from './db.js' 完成评估。

方案 2：CLI 启动参数预加载（无代码侵入）

在生产规范或容器化部署中，通常不建议在业务代码中硬编码加载逻辑，更推荐通过 Node 运行时参数进行预注入。在 Node.js 21 中，使用 --import 参数可以在主模块加载前挂载模块：

# 推荐：Node.js 21 ESM 现代预加载参数
node --import dotenv/config index.js

# 兼容旧版本 CommonJS 习惯的参数
node -r dotenv/config index.js

使用这种方式时，index.js 完全不需要书写任何 import dotenv 语句，代码保持纯粹，且环境变量在整个 Node 运行时初始化之初就已经就绪。

方案 3：动态导入（Top-level await）

如果需要在加载环境变量时动态指定 .env 文件路径（例如根据运行时传入的参数区分测试或开发配置），静态 import 无法接收动态传参。此时可以利用 Node.js 21 原生支持的顶层 await 与动态 import() 配合：

// index.js
import dotenv from 'dotenv';

// 1. 显式完成配置加载
dotenv.config({ path: process.env.CUSTOM_ENV_PATH || '.env' });

// 2. 动态导入业务模块，确保此时环境变量已经填充
const { connectDB } = await import('./db.js');

connectDB();

三、Node.js 21 原生能力：无需 dotenv 的 --env-file

自 Node.js 20.6.0 开始并作为重要能力贯穿 Node.js 21，Node 运行时官方内置了对 .env 文件的原生解析支持。使用该特性时，项目无需安装 dotenv 依赖包，更完全避开了 ESM 导入提升带来的顺序陷阱。

1. 基本使用方式

# 启动时直接传入 --env-file 参数指定文件路径
node --env-file=.env index.js

由于 Node.js 运行时在解析任何 JavaScript 代码之前就已经完成了 --env-file 的读取与系统级注入，因此业务代码中无论静态导入还是动态执行，任何位置均可直接安全访问 process.env.KEY。

2. 多环境文件级联覆盖

Node.js 21 原生支持同时指定多个环境变量配置文件。当多个文件中存在同名键时，后指定的配置会覆盖先指定的配置：

# 先加载通用配置，再用本地个性化配置进行覆盖
node --env-file=.env --env-file=.env.local index.js

四、避坑注意事项与生产环境最佳实践

无论是使用 dotenv 还是原生的 --env-file，在 ESM 模式下处理环境变量时都应当遵循以下原则：

• 所有环境变量均被读取为字符串：process.env.IS_ACTIVE = "false" 在布尔判断 if (process.env.IS_ACTIVE) 中依然为真（非空字符串视为 true）。数值和布尔值必须显式做类型转换，如 Boolean(process.env.IS_ACTIVE === 'true')。
• 绝对禁止将包含凭据的 .env 提交至代码仓库：在 .gitignore 中务必添加 .env 以及 .env.*.local，仅提交包含变量名与说明的 .env.example 供团队成员参考。
• 系统预设环境变量优先级更高：当操作系统、CI/CD 流水线或容器环境已经设置了 PORT=8080，dotenv 默认策略不会覆盖已存在的系统变量。如需强制覆盖，需显式传入 override: true 参数。
• 多层嵌套子模块避免重复读取：建议将环境变量的读取与校验集中收口在统一的 config.js 模块中，对外导出经过校验的强类型配置对象，避免在各业务文件中散落调用 process.env。

五、总结

在 Node.js 21 的 ESM 模块体系中加载 dotenv，理解 ESM 的静态导入提升时序是关键。针对不同的场景，推荐采用以下策略：

• 快速开发与单工程代码级管理：在入口文件首行使用 import 'dotenv/config'。
• 代码解耦与标准启动流程：使用 node --import dotenv/config app.js 预载入。
• Node.js 21 新工程或轻量级服务：直接使用运行时内置的 node --env-file=.env app.js，彻底摆脱三方包依赖与导入时序问题。