调试Node.js ES模块：调试器未在未捕获异常处断点

问题场景 #

使用Node.js v19.2.0，通过Inspector Client（node inspect、Chrome调试器、VSCode调试器）调试代码时，CommonJS脚本与ES模块出现明显差异：

测试用极简代码：

throw new Error("err");

分别保存为test.js（CommonJS格式）和test.mjs（ES模块格式），调试后现象如下：

• 调试CommonJS脚本：调试器会在异常抛出的代码行自动断点
• 调试ES模块：调试器不会在用户脚本的异常处断点，反而停在node:internal/modules/esm/module_job:194的await this.module.evaluate(timeout, breakOnSigint);行（该行处于ES模块加载内部的try-catch语句中）

问题解答 #

1. 这是普遍现象还是环境问题？ #

这是普遍现象，并非你的环境问题。根源在于ES模块的异步加载机制：Node.js对ESM的加载和评估逻辑做了异步封装，并用try-catch捕获了模块执行中的异常，导致调试器的未捕获异常断点逻辑无法直接关联到用户代码的抛出位置。

2. 是否为已知问题？ #

是Node.js的已知问题，官方仓库中已有相关议题讨论ESM调试时的异常断点跳转问题，核心矛盾是ESM异步加载的内部错误处理机制，打断了调试器对用户代码异常的直接定位。

3. 如何让ESM调试表现与CommonJS一致？ #

可以尝试以下几种方案：

• 手动设置断点：在ESM脚本的异常行或开头手动添加断点，调试器会正常停在用户代码处
• 启用源映射：启动调试时添加--enable-source-maps参数，例如：node --enable-source-maps inspect test.mjs，帮助调试器更好地映射内部执行逻辑到用户模块，部分场景下可自动定位到异常抛出点
• 升级Node.js版本：Node.js v20及后续版本对ESM调试的异常处理逻辑做了优化，升级后大概率解决该问题
• 临时捕获重抛：在ESM脚本顶层用try-catch包裹代码后重新抛出，让调试器能捕获到顶层异常：

  try {
    throw new Error("err");
  } catch (e) {
    throw e;
  }
  

内容的提问来源于stack exchange，提问作者Mad Dog