使用dotenv加载.env环境变量始终返回undefined的排查求助

1. 路径拼接错误（最高发原因） #

你当前使用__dirname拼接.env路径，存在两种常见异常场景：

• 若项目package.json中配置了"type": "module"使用ES模块规范，Node原生不提供__dirname变量，拼接出的路径为undefined/.env，无法定位到正确文件
• 若使用TS或打包工具，编译后的产物通常输出在dist等子目录下，__dirname指向产物所在目录，而.env存放在项目根目录，自然找不到文件

解决方法： #

ES模块环境下使用如下方式获取正确的.env路径：

import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
// 若编译后文件在dist目录，需要回退到根目录，按实际目录结构调整层级
const dotenvAbsolutePath = join(__dirname, '../.env')

打印拼接出的路径，手动确认该路径下是否存在.env文件。

2. .env文件本身异常 #

• 文件名错误：Windows系统默认隐藏后缀名，很容易将文件命名为.env.txt而非.env，请关闭系统的「隐藏已知文件类型的扩展名」选项确认文件名
• 格式错误：如果文件带UTF-8 BOM（通常是Windows记事本保存导致）、变量定义带多余空格/标点，都会导致解析无结果且不报错

解决方法： #

• 确认文件名为纯.env，无前缀后缀
• 参考如下规范编写.env文件，不要加多余引号、空格：

AWS_ACCESS_KEY_ID=你的AK值
AWS_SECRET_KEY=你的SK值
AWS_REGION=你的区域值

3. 模块规范混用问题 #

你代码中同时使用了ES模块的import和CommonJS的require，运行时可能出现加载异常

解决方法： #

统一使用ES模块的dotenv加载方式：

import * as dotenv from 'dotenv'
// 路径确认正确后传入config
dotenv.config({ path: dotenvAbsolutePath })

验证方法 #

添加打印逻辑确认加载结果：

console.log('加载的env内容：', dotenv.config({ path: dotenvAbsolutePath }))

如果返回结果中parsed字段有内容，说明文件加载解析成功，若process.env还是取不到值，检查是否有其他逻辑在dotenv加载后覆盖了对应的环境变量。

内容的提问来源于stack exchange，提问作者Pleasant Nightmares