vscode调试node.js时--experimental-modules报错,因node.js≥14已默认启用esm,该标志在v16+被彻底废弃;硬加会导致node: bad option错误,且与调试参数冲突。

VSCode 里用 --experimental-modules 已经过时,直接禁用它——Node.js ≥ 14 后该标志被移除,硬加反而导致调试失败。
为什么 launch.json 里写 --experimental-modules 会报错
Node.js 自 v14.0.0 起默认启用 ESM 支持,--experimental-modules 标志在 v16.0.0 中被彻底废弃。VSCode 的调试器若在 runtimeArgs 里强行加入该参数,会触发:node: bad option: --experimental-modules。
- 错误常出现在老项目迁移或复制了过时的配置模板
- 哪怕
node -v显示 v12.x,VSCode 调试器也可能调用系统 PATH 里的另一个高版本 Node,造成行为不一致 - 该参数和 VSCode 自动注入的
--inspect等调试参数冲突,尤其在 ESM 模式下 loader 链路更敏感
.mjs 文件在 VSCode 调试时路径加载失败的真正原因
不是后缀没识别,而是 VSCode 启动调试进程时工作目录(cwd)与你预期不符,导致相对路径解析错位。比如 import './config.js' 在终端运行正常,F5 后却报 Cannot find module './config.js'。
使用 JSON Schema 验证 JSON 数据,从示例 JSON 生成 schema,并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
- 检查
launch.json是否显式设置了"cwd";没设则默认为${workspaceFolder},但若program指向子目录(如"${workspaceFolder}/src/index.mjs"),模块解析仍以 workspace 根为基准 - ESM 的
import是基于文件物理路径解析的,不走node_modules的resolve规则,所以./config必须真实存在且大小写、扩展名完全匹配 - Windows 下路径分隔符混用(
\vs/)在 ESM 导入语句中会导致解析失败,建议统一用/或动态拼接
如何让 import 正确加载本地路径(含别名/非标准位置)
ESM 原生不支持 paths 别名或自动补 .js,必须显式声明扩展名,或靠工具层介入。
- 所有
import语句必须带后缀:import { foo } from './utils.js',不能写成from './utils'(除非配了exports字段) - 想用别名(如
@/lib),得配合node --loader(如ts-node/esm或esbuild-node-loader),但 VSCode 调试器不兼容手动指定--loader,会与内置调试参数冲突 - 更稳妥的做法:用构建工具(如
esbuild或vite build --ssr)提前将路径转为绝对物理路径,再调试生成后的.js文件 - 如果坚持调试源码,把
package.json的"type": "module"和所有.js文件统一管理,比混用.mjs+.js更少出路径歧义
最易被忽略的一点:VSCode 调试器对 ESM 的路径解析是严格静态的,它不会像 CommonJS 那样尝试补全扩展名或遍历 index.js。任何路径偏差都会立刻暴露,而不是静默 fallback。










