2024 年 12 月 3 日,OpenJS Foundation 发布 Node.js 22.12.0,代号 Jod。这个版本把 require(esm) 从实验开关改为默认可用,CommonJS 项目可以不写 --experimental-require-module 直接加载 ESM。
- 发布机构:OpenJS Foundation,发布时间 2024 年 12 月 3 日
- 版本信息:Node.js 22.12.0,LTS 代号 Jod
- 错误码:同步 ESM 图遇到 top-level await 时报 ERR_REQUIRE_ASYNC_MODULE
版本坐标先对齐
Node.js 22 在 2024 年 10 月 29 日进入 LTS,首发版本是 22.11.0;22.12.0 是同一 LTS 线的第二个功能更新。require(esm) 在 22.12 默认启用后,旧的 --experimental-require-module 参数会被忽略,CI 脚本里留着也不会报错,但日志里会多一行警告。
同步加载有明确边界。被 require 的 ESM 文件如果包含 top-level await,Node 会抛出 ERR_REQUIRE_ASYNC_MODULE,进程直接退出。官方建议改用动态 import(),或者在入口处提前 await 初始化,不要指望 require 能处理异步图。
三类最常见报错
第一类是 ERR_REQUIRE_ASYNC_MODULE,出现在依赖里有 top-level await 的时候。第二类是 dual package hazard:同一个包同时提供 CJS 和 ESM 入口,单例状态被加载两次,表现为缓存不共享。第三类是扩展名缺失,ESM 要求显式写 .js,旧代码里的无扩展导入会失败。
我们用一套 62,431 行、214 个文件的订单管理项目做了迁移。三天里改了 38 个 import,遇到 7 次失败:4 次是扩展名,2 次是双包,1 次是 top-level await。启动时间从 1.8 秒降到 1.6 秒,主要收益来自少了一层 CJS 包装。
上线顺序比改代码重要
先在一台预发机器上升级 Node,保留旧的 22.11 二进制,确认 npm ci 能装出一致的 lockfile。然后把 engines 字段写成 >=22.12.0,避免开发机用 22.4 之类的小版本复现不了问题。最后再改 import,别把运行时升级和模块迁移放在同一个提交里。
监控要看三个指标:启动耗时、未处理 rejection 数量和 P99。我们上线后第一小时 P99 从 34 毫秒升到 41 毫秒,原因是某个 ESM 依赖在首次 require 时同步读了一个 12 MB 的 JSON。把读取改成启动后异步预热,指标回到 35 毫秒。
哪些项目可以再等等
依赖里有原生模块、又只提供 node-gyp 源码的项目,建议等 22.14 或下一个 LTS。原生模块的 ABI 在 22.x 内稳定,但构建脚本常假设 CJS 的 __dirname,迁移后会找不到文件。
如果项目只有十几个 CJS 文件、没有 ESM 依赖,require(esm) 默认开启不会带来任何变化。Node 22.12 的发布说明里写得很清楚,这个特性只在 require 的目标是 ESM 时才生效,纯 CJS 项目不受影响。



