跳到正文
每周二、五更新 · 排障记录与可运行代码邮件订阅:hi@xiaoming1.cn
编程心得标志,字母 A 与代码尖括号组合编程心得Awesome Dev

Node.js 22.12 默认打开 require(esm),旧项目先查这三处

多块屏幕上同时显示代码、日志与运行状态
多块屏幕上同时显示代码、日志与运行状态。配图为免费图库实拍,与本文主题对应。

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 项目不受影响。

文中提到的命令与数据来自公开版本说明和本站测试机。换环境后数值会变,先在小规模数据上复跑一遍,再动生产。

相关

读完可以接着看

两件与本文问题域直接相关的产品。

把下一次故障写成可复用的记录

每周二、五发一封邮件,只放当周的排障笔记、命令清单和一处容易踩错的细节。不发广告,随时可退。

hi@xiaoming1.cn

也可以直接打电话:0668-339 7712,工作日 09:30 至 18:00。