必须启用autoattachchildprocesses:true,否则vs code仅调试主进程;它使调试器自动附加fork子进程和worker threads,但需配合--inspect-brk、唯一端口及正确sourcemap配置。

VSCode 本身不提供“并发运行环境”这个抽象概念,所谓多任务处理调试,本质是正确配置 Node.js 的多进程(child_process.fork)或多线程(Worker)调试链路——关键不在开几个终端,而在让 VS Code 主动附加子进程。
为什么开了多个终端还不能跨进程调试
在集成终端里分别执行 node main.js 和 node worker.js,只是启动了两个独立的、互不感知的 Node 进程。断点只对当前终端生效,调用栈不联动,变量无法跨上下文查看,也无法单步跟进从主进程到子进程的逻辑流。
- VS Code 默认只调试
launch配置中program指向的那个进程 -
autoAttachChildProcesses: true是唯一能触发自动附加的开关,但它只对符合规范的子进程起作用 - 手动开终端 ≠ 启用调试器的子进程监听机制
必须开启 autoAttachChildProcesses 并配对端口
该字段不是可选项,而是子进程调试的启用前提。它让 vscode-js-debug 在父进程启动时监听 fork() 和 new Worker() 创建的新进程,并尝试建立调试会话。
- 只对
child_process.fork()和Worker构造函数创建的子进程有效;spawn()必须显式加--inspect-brk才被识别 -
launch.json中需同时设置:"port": 9229(或其它未被占用端口)、"runtimeArgs": ["--inspect-brk=9229"]、"autoAttachChildProcesses": true - 若多个
Worker实例共用同一端口,调试器只会连上第一个——建议不指定端口,让 Node 自动分配(即删掉=9229),或为每个 Worker 动态传入唯一端口
fork() 子进程断点不命中?大概率漏了 execArgv
用 fork('./worker.js') 启动子进程时,Node 默认不会开启调试端口。即使启用了 autoAttachChildProcesses,也会因端口未暴露而跳过附加。
- 正确写法:
fork('./worker.js', [], { execArgv: ['--inspect-brk=9229'] }) - 如果项目用
ts-node或esbuild-node启动主进程,autoAttachChildProcesses会失效——它们绕过了标准 Node 启动流程 - macOS/Linux 下用 nvm 管理 Node 版本时,必须在
launch.json中显式写"runtimeExecutable",否则子进程可能继承错误的 Node 可执行路径
Worker 调试失败的典型场景和绕过方式
ESM 项目中 Worker 调试失败,常因模块系统错位:Node 默认按 CommonJS 解析,遇到 import 就崩;而 Worker 实例又默认不读取 package.json 的 "type": "module"。
- 确保主进程和 Worker 文件所在目录的
package.json都声明了"type": "module" - 不要用
code-runner直接运行 Worker 文件——它不走调试协议,断点无效 - 若 Worker 依赖 TypeScript,别直接传
.ts路径;要么预编译成 JS 后引用,要么改用runtimeExecutable: "npx"+runtimeArgs: ["ts-node", "--loader", "ts-node/esm", "./worker.ts"]
真正难的不是配 launch.json,而是理解哪些子进程会被调试器“看见”、哪些被忽略,以及为什么忽略——比如 spawn() 不带 --inspect、ts-node 启动、GUI 启动 VS Code 导致环境变量缺失,这些细节一漏,整个多任务调试链就断在第一环。











