Node.js报Cannot use import statement outside a module与ERR_REQUIRE_ESM的排查方法(type:module、.mjs与createRequire定位)

node app.js跑起来报SyntaxError: Cannot use import statement outside a module,或者升级某个依赖后报Error [ERR_REQUIRE_ESM]: require() of ES Module not supported,两种报错都出在模块加载阶段,方向正好相反。前者是文件按CommonJS解析却写了import,后者是CommonJS代码用require去加载一个只发ESM的包。把文件和依赖各自的模块类型判清楚,再决定改代码、改package.json还是升Node,比一上来就动import写法省事。


两套模块系统怎么判

Node.js从很早就有两套模块系统,CommonJS用require和module.exports,ESM用import和export,一个.js文件到底按哪套解析,由它最近的package.json里的type字段决定:没写type或者写commonjs就按CommonJS,写module才按ESM,.mjs强制ESM、.cjs强制CommonJS,跟type无关。SyntaxError: Cannot use import statement outside a module说的是文件被当成CommonJS,偏偏里面有import,除了没配type,还有几种成因:跑的是.cjs、或者有工具把代码包成CommonJS、或者Node版本太老没有语法检测。ERR_REQUIRE_ESM反过来,是CommonJS这边require了一个只发ESM的包,chalk、p-limit、got、execa都在某个大版本之后去掉了CommonJS入口。报错原文里那个/node_modules/xxx/index.js路径直接点名了是哪个包,先照着查它的package.json。之前接手一个Node 18的项目,升级p-limit到4之后全站报ERR_REQUIRE_ESM,回退版本才压住,其实升一下Node就能用。

node -v
cat package.json
node -p "require('./node_modules/chalk/package.json').type"

报错串里那个包路径就是线索,别先去改自己的业务代码。

SyntaxError按文件类型改

要让import生效,最直接的改法是在package.json里加"type": "module",这个作用域内所有.js都按ESM解析;只想改单个文件就把它重命名成.mjs,不用动package.json。浏览器里则是给script标签加type="module",普通script里写import同样报这句SyntaxError。新一点的Node有语法检测,.js文件开头出现import或export就按ESM跑,Node 22.7.0、20.19.0、24.0.0,这条行为是分批放开的,老版本没有检测、必须显式配type。实测把type加上之后,原来能跑的require会立刻变成ReferenceError: require is not defined in ES module scope,__dirname和__filename也跟着失效,这是切换模块系统的连带反应,不是新报错。package.json缺type时Node还会给MODULE_TYPELESS_PACKAGE_JSON警告,顺手把type补上就消失了。

ERR_REQUIRE_ESM按Node版本选改法

require能不能加载ESM,全看node -v落在哪一段。Node.js 20.17.0、20.19.0、22.12.0、22.13.0、23.5.0,这条时间线要记清:22.0.0先加--experimental-require-module开关,20.17.0回移到20分支,23.0.0和22.12.0、20.19.0默认开启,22.13.0与23.5.0去掉默认实验性警告,25.4.0把它标成稳定。所以升到22.12.0或20.19.0之后,多数老项目的ERR_REQUIRE_ESM会直接消失,这是首选改法。不能升Node就用动态import(),把那一处require换成await import('包名'),注意它返回Promise、要放进async函数或者接.then。还有个坑:require一个ESM拿回的是模块命名空间对象,只有default导出时才能直接当函数用,混导出要取.default,见过升完Node报chalk is not a function的,就是这个原因。依赖图里有顶层await时require改报ERR_REQUIRE_ASYNC_MODULE,只能走动态import。不想折腾就把包锁回最后一个CommonJS大版本,p-limit 3.1.0、4.0.0、6.2.0,对应的是能不能用require的分界线。TypeScript项目还要看tsconfig,module设成commonjs会把源码里的import()编译成require(),改运行时写法没用,得把module与moduleResolution都设成nodenext。

node --experimental-require-module app.js
npm ls p-limit chalk

升Node能解决大部分,但别忽略.default和顶层await这两个后续坑。

ESM项目里另外几个连带报错

切成ESM之后,require is not defined in ES module scope、__dirname is not defined、ERR_MODULE_NOT_FOUND、ERR_PACKAGE_PATH_NOT_EXPORTED会陆续冒出来,都是同一套规则的不同侧面。ESM不做扩展名补全,相对导入import './utils'要写成import './utils.js',漏了.js就是ERR_MODULE_NOT_FOUND;导入包里没在exports字段列出的子路径,报ERR_PACKAGE_PATH_NOT_EXPORTED,只能改导入路径或者给包提issue。__dirname用import.meta.dirname顶替,Node 20.11.0、21.2.0、24.0.0,之后才支持,老写法得用fileURLToPath(import.meta.url)配dirname自己拼。真需要在ESM里同步加载CommonJS,用createRequire造一个require出来即可,踩过一次的是把createRequire写在循环里反复构造,其实模块顶层建一次就够。测试框架也常卡在这,Jest 30.4.0、30.5.0,对require ESM的支持各有条件,老版本跑ESM要加--experimental-vm-modules和NODE_OPTIONS。

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);

TypeScript与打包器那一层

源码看着是ESM、运行时报的却是ERR_REQUIRE_ESM,多半卡在编译配置。tsconfig里module设commonjs时,TypeScript把import和import()都编译成require(),产物是CommonJS,加载只发ESM的包就炸。把module设成nodenext或node16,编译器会依据最近的package.json的type决定产物格式,.mts出.mjs、.cts出.cjs,跟运行时的扩展名规则对得上。moduleResolution别只改一半,新版本TypeScript会由module推断它,老版本得显式配一致。双格式发布的库靠package.json的exports按require和import两种条件指向不同文件,打包器解析错条件也会报ERR_REQUIRE_ESM,这时候改应用代码没用,得查解析配置。查了半天才发现是webpack把require条件挑给了ESM-only的包,这种事在升级构建工具之后特别常见。

现场遇到过的组合是tsconfig里module写commonjs、源码用import()动态加载,编译产物退回require(),Node 18上直接报ERR_REQUIRE_ESM,改运行时的import写法没用,得把module与moduleResolution都改成nodenext。按报错串先定是CJS还是ESM,再看node -v落在哪一段,比重装node_modules省事。数据截至2026年11月。