VSCode默认不调试子进程,断点不触发是因调试会话未覆盖子进程;必须设"autoAttachChildProcesses":true(仅对"type":"node"且"request":"launch"生效),用fork()而非spawn(),确保Node≥14、端口不冲突、路径绝对且重启调试会话。

VSCode 默认不调试子进程,断点不触发不是代码问题,而是调试会话根本没覆盖到子进程——必须显式启用自动附加机制,并确保父子进程都满足调试握手条件。
Node.js 子进程断点不触发:检查 autoAttachChildProcesses 是否生效
这个字段只在 "type": "node" 且 "request": "launch" 的 launch 配置中起作用,pwa-node 或 attach 模式下完全忽略它。常见错误包括:
- 误用
"type": "pwa-node":老项目迁移时容易保留该配置,但 autoAttachChildProcesses 不支持 pwa-node - launch.json 里写了
"request": "attach":autoAttachChildProcesses 对 attach 模式无效,必须改回"launch" - 配置写在错误的 configuration 下:比如你有多个配置项,但
autoAttachChildProcesses: true只加在了测试配置里,而实际运行的是开发配置 - 没重启调试会话:改完 launch.json 后必须停止当前调试并重新按 F5,热重载不生效
子进程启动方式决定能否被自动附加
child_process.fork() 是唯一被 VSCode JS Debugger 原生支持的自动附加路径;spawn() 默认不触发自动附加,除非你手动加 --inspect 并确保命令以 node 开头。
- ✅ 推荐:
fork('./worker.js')—— 无需传--inspect,VSCode 自动注入 - ❌ 避免:
spawn('node', ['worker.js'])—— 缺少--inspect,且未指定端口,VSCode 无法识别为可调试 Node 子进程 - ⚠️ 强行用 spawn():必须写成
spawn('node', ['--inspect=0.0.0.0:9230', 'worker.js']),且端口不能与主进程(默认 9229)冲突 - ? Windows 上用
cmd /c node worker.js包裹:VSCode 无法识别为 Node 进程,autoAttach 失效
Python 多进程调试:依赖 subProcess: true 和 debugpy 版本
Python 扩展从 1.84+ 开始支持 "subProcess": true,但它不是魔法开关——底层靠 debugpy 注入,因此版本和初始化时机很关键。
- 必须安装
debugpy >= 1.6.0,且主进程和所有子进程环境都要能 import 到(虚拟环境隔离时尤其注意) -
"subProcess": true仅对"type": "python"+"request": "launch"生效,不能用于attach配置 - 若子进程由
subprocess.Popen(['python', ...])启动,而非multiprocessing或concurrent.futures,则不会被自动捕获 - 断点显示为空心圆?检查子进程工作目录是否与 VSCode 当前 workspaceFolder 一致;路径不匹配会导致 source map 解析失败
端口、超时与进程层级的隐藏限制
VSCode 的自动附加不是无条件监听所有子进程,它有明确边界和容错窗口。
- 端口必须唯一:主进程用 9229,子进程建议用
9230、9231等,重复会触发EADDRINUSE,子进程静默崩溃 - 只 attach 直接子进程:由主进程
fork()启动的进程会被捕获,但该子进程再fork()出来的“孙进程”不会 - 5 秒超时机制:子进程启动后需在 5 秒内暴露调试端口,否则 VSCode 放弃等待;可加
"timeout": 10000延长 - Node.js 版本底线是
≥ 14:低于此版本async_hooks不稳定,部分子进程生命周期事件可能丢失
真正难调的场景(比如 worker_threads 和 child_process 混用、或子进程又启动了 shell 命令),别强依赖自动附加——改用 --inspect-brk + 手动 attach 更可控,而且能第一时间确认子进程是否真的跑起来了。











