Node报ERR_REQUIRE_ESM怎么查
适用范围:Node.js的CommonJS和ES模块;不同版本加载能力不同,示例用于隔离测试目录。
依赖升级后,原来的 require() 突然失败,先判断是“CommonJS去加载ES模块”,还是“当前文件已被当成ES模块,里面却继续使用require”。两种情况的修复位置不同。
还有一个常被旧教程忽略的变化:部分较新的Node.js版本已经支持用 require() 加载符合条件的同步ES模块。因此不能只看错误名称就断言所有环境必须降级依赖,必须结合实际运行版本和模块结构判断。[1]
查看启动服务的Node,而不是只看当前终端
在项目运行入口对应的环境中检查:
node --version
node -p "process.execPath"
服务管理器、容器和交互终端可能调用不同的Node。报错中的文件路径也要保留:它通常指出是哪一个调用文件、哪一个依赖首先发生格式冲突。
核对目标文件后缀、最近一级适用的 package.json 的 type,以及依赖的版本与导出声明。不要为了修一个文件,直接把项目顶层的 type 改成另一个值,这可能改变许多 .js 文件的解释方式。
区分三类常见现象
| 现象 | 先判断什么 |
|---|---|
| ERR_REQUIRE_ESM | 当前运行时和调用方式是否支持目标ES模块,是否升级过依赖 |
| require is not defined in ES module scope | 当前文件是否已经按ES模块执行,代码是否仍是CommonJS写法 |
| ERR_REQUIRE_ASYNC_MODULE | 被require加载的模块或其依赖图是否包含顶层await |
.mjs 明确采用ES模块,.cjs 明确采用CommonJS;.js 还要结合包配置以及具体Node版本的规则。支持同步加载ES模块,不等于支持同步等待任意顶层异步代码。[1][2]
CommonJS可以用动态import加载ES模块
在新的空目录放两个小文件,避免改动线上入口。第一个文件名为 hello.mjs:
export const message = 'ok';
第二个文件名为 demo.cjs:
(async () => {
const { message } = await import('./hello.mjs');
console.log(message);
})().catch((error) => {
console.error(error);
process.exitCode = 1;
});
执行 node demo.cjs,应输出 ok。示例只说明动态加载方式,不是对所有依赖的直接替换模板。真实包可能采用默认导出而非命名导出,要根据实际导出接口取值;异步初始化也可能需要调整调用顺序。
若决定整体迁移到ES模块,还需处理路径写法、配置文件、测试工具及入口等兼容问题,不是把几处 require 换成 import 就完成。
在测试分支修复,不直接改node_modules
先保留原锁文件和当前可用版本。确认错误来自哪个依赖后,在测试分支选择项目支持的运行时或兼容接口。临时回退依赖需要检查维护和安全状态,不能长期停在不再维护的版本。
不要直接编辑 node_modules 里的依赖源码,重新安装会丢失修改。修复应落在自己的代码、依赖约束和受控补丁中。
复测应覆盖真实启动命令
使用相同Node路径、锁文件和启动参数做干净安装、构建与功能测试。确认首次加载和异步初始化都完成,不能只凭 node --check 语法检查通过就上线。提交工单提供Node版本、入口文件类型、相关 type 设置和首个报错,不发送整个配置文件中的密钥。
继续排查
Node.js项目上线:域名访问、后台运行与重启恢复;npm ci提示锁文件不一致怎么办。
技术依据:[1] Node.js CommonJS与require加载ES模块;[2] Node.js ES模块。适用版本见本文说明。