VSCode运行.mjs文件：Node.js ESM模块运行指南

用过 Hono 的朋友大概都遇到过这个坑：在 VSCode 里按 F5 想调试项目，结果 Node.js 直接报错——要么是 Cannot use import statement outside a module，要么是 Unexpected token '<'。说到底，Hono 依赖 JSX/TSX 语法、顶层 await 和 ESM 特性，直接拿 node 跑肯定不行，必须用 tsx 启动。但话说回来，即便只是调试普通的 .mjs 文件，VSCode 也未必能一次跑通。

先说结论：VSCode 确实能直接运行 .mjs 文件，但有两个硬前提——Node.js 版本不低于 12.0.0，同时文件必须被正确识别为 ESM。只要有一个不满足，你看到的就会是 SyntaxError: Cannot use import statement outside a module。

为什么 node index.mjs 明明成功，VSCode 调试器却报错？

问题出在 VSCode 调试器的启动方式上。launch.json 默认按 CommonJS 模式启动，即便文件后缀是 .mjs，它也可能忽略 ESM 规则——尤其是在旧版 VSCode（比如 1.60 以下）中，这一现象特别明显。那该怎么破？

• 首先确认 Node.js 版本：node -v 必须 ≥ 14（推荐直接用 18 以上），否则 --inspect 协议在 ESM 调试时会出兼容问题。
• launch.json 里千万别手动加 --loader 或 --input-type=module——这俩参数会和 VSCode 自动注入的调试参数打架，轻则断点失效，重则直接崩溃。
• 正确的做法是让 VSCode 根据文件扩展名自动识别：把 program 字段写成 "${workspaceFolder}/index.mjs"，并确保路径真实存在、没有拼写错误。文件摆在那儿，VSCode 才能认得出来。
• 如果断点显示为灰色，别急着怀疑代码——检查一下 launch.json 里的 type 字段。ESM 调试必须用 "type": "node"，如果误写成 chrome 或 pwa-node，调试器根本不会按 Node.js 的方式去解析模块。

package.json 里配了 "type": "module"，同时又用 .mjs 文件，会冲突吗？

两者并不冲突，但优先级有明确区别。.mjs 后缀的优先级最高——Node.js 会完全无视 package.json 里的 type 字段，强制按 ESM 解析。真正依赖 type 字段的其实是 .js 文件。这里有几个常见的混用陷阱：

• 如果项目里既有 index.mjs 又有 utils.js，而 utils.js 里用了 import 语法却没配 "type": "module"，那么报错的就是 utils.js 而不是主文件。
• 建议统一策略：要么全用 .mjs 后缀，然后删掉 package.json 里的 type 字段；要么只保留 .js 扩展名，完全靠 package.json 控制，不要混用两种方式。
• 另外千万注意：require() 在 ESM 环境下不可用，即便在 .mjs 文件里调用也会报 ReferenceError: require is not defined。这个坑踩到的人不少。

终端里 node index.mjs 跑得好好的，一按 F5 就挂——典型原因有这些

F5 启动的是调试协议（--inspect），和普通执行是两码事。调试器对模块解析路径、工作目录，甚至 Node.js 内部 loader 的链路都更敏感。以下几个原因是最常见的绊脚石：

• cwd 字段缺失或写错了：如果 launch.json 里没有设置 "cwd": "${workspaceFolder}"，Node.js 可能会从 VSCode 安装目录启动，结果 import 的相对路径统统找不到。
• 路径里包含空格或中文：虽然 VSCode 通常能自动处理，但某些旧版本对 .mjs 文件的路径解析仍然有 bug。临时解决办法是把项目移到纯英文无空格的路径下，比如 /tmp/myapp。
• 如果你用了 nodemon 并直接改了 runtimeExecutable，这会导致 VSCode 无法注入调试参数。正确做法是用 runtimeArgs + runtimeExecutable 组合，并且 runtimeArgs 里不要重复写 --inspect。
• VSCode 缓存也可能造成问题：修改 launch.json 后没重启调试会话，或者之前残留的断点导致状态错乱。最直接的排查方式：关闭所有窗口，重新打开文件夹再试一次。

说到底，真正卡住你的往往不是语法本身，而是 Node.js 对 ESM 的路径解析规则，以及 VSCode 调试器对 --inspect 参数的接管方式。这两者只要稍微错位一点，import 就会找不到模块，断点也会永远灰着。小小建议：动手调试之前，先在终端里跑一遍 node index.mjs 确认文件能正常执行，然后再去配 launch.json——这个顺序反过来排查，效率会高得多。