vscode不支持单个configuration启动多个程序，因每个configuration仅对应一个调试器实例；多环境联调须通过launch.json中定义多个独立configurations并用compounds组合触发，且需满足名称精确匹配、顶层定义、request字段明确等硬性条件。

VSCode 本身不支持“为同一个项目配置多个启动目标”这种说法——它没有“项目级启动目标”的概念，只有 launch.json 中定义的 configurations（每个是独立调试会话）和 compounds（协调多个已有 configuration 的触发顺序）。所谓“多环境联调”，本质是组合、复用、隔离这些配置，而非给一个项目打上多个启动标签。

为什么不能直接在单个 configuration 里写多个程序

VSCode 的每个 configuration 对应一个调试器实例（如 debugpy、node、coreclr），它只能 attach 或 launch 一个进程。你无法在一个 configuration 的 args 里塞两个服务命令，也不能让 type: "node" 同时跑前端 + 后端。

• 强行合并会导致调试器无法识别入口、断点失效、控制台混杂、停止调试时只杀一个进程
• preLaunchTask 只能执行构建类任务，不是服务管理工具；它不等待服务真正就绪（比如端口监听），只等 shell 命令退出
• 如果你看到“启动多个程序”的示例，它们一定是在 configurations 数组里定义了多个独立项，再通过 compounds 组合

compound 配置必须满足的硬性条件

compounds 不是魔法开关，它只做一件事：按数组顺序依次触发已存在的 configurations 名称。任何不满足以下任一条件的 compound 都会静默失败或报错 Configuration 'xxx' not found：

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 所有被引用的 name（如 "FastAPI Server"）必须已出现在同一 launch.json 的 configurations 列表中，拼写、大小写、空格必须完全一致
• compounds 必须定义在 launch.json 根对象下，且是顶层字段，不能嵌套在 configurations 里
• 每个子 configuration 必须有明确的 request 字段（"launch" 或 "attach"），"attach" 类型不会自动等待目标进程，需额外保障（如用 shell 脚本轮询端口）
• 环境变量不会跨 configuration 透传，envFile 是最稳妥的统一加载方式，而不是靠父级 compound 注入

如何安全实现前后端联调（典型场景）

以 React 前端 + FastAPI 后端为例，常见错误是把前端启动写成 command: "npm start" 放进 debugpy 配置里——这根本不会被调试器接管。正确做法是分层处理：

• 后端用 debugpy 启动并监听调试端口："type": "debugpy"，"request": "launch"，确保 justMyCode: true 避免进入依赖源码
• 前端用 chrome 或 pwa-chrome 类型配置，"request": "launch" 并设置 "url": "http://localhost:3000"，靠 serverReadyAction 捕获 Compiled successfully 后再打开浏览器
• 两者都定义好后，在 compounds 中声明："configurations": ["FastAPI Server", "React Frontend"]，并设 "stopAll": true 确保 F5 停止时全部关闭
• 如果前端依赖后端就绪，不要指望 compound 自动等待——加一个 preLaunchTask 调用 curl -f http://localhost:8000/health 或用 Node.js 脚本轮询，失败则退出

容易被忽略的兼容性与调试盲区

复合启动看似简单，但实际落地时几个细节常导致“看起来启动了，但联调不通”：

• cwd（工作目录）必须各自准确：前端配置的 cwd 应指向 frontend/ 目录，后端指向 backend/，错位会导致 package.json 或 pyproject.toml 找不到
• Windows 下 cmd/shell 默认不支持并发命令（如 start cmd /c "npm run dev" && python main.py），compound 是唯一可靠方案；但 Linux/macOS 用户误以为可以用 shell 类型配置搞定一切，结果调试器无法 attach 子进程
• console: "integratedTerminal" 会让多个服务输出挤在同一个终端页签里，建议为每个 configuration 设置不同 consoleName，便于区分日志流
• 如果你在 WSL2 中调试 Windows 主机上的 Chrome，pwa-chrome 的 port 和 url 需显式写成 http://localhost:3000 而非 http://127.0.0.1:3000，否则浏览器可能拒绝连接

真正难的从来不是写几行 JSON，而是厘清每个配置背后代表的进程生命周期、调试器挂载时机、以及环境变量的实际作用域。compound 只负责“喊名字”，谁来响应、何时响应、响应是否成功，全得靠你一个个对齐。