如何让 Xdebug 同时连接两个不同端口的 VS Code 实例进行并行调试

xdebug 本身不支持按请求动态切换调试端口，但可通过 dbgp 代理或 xdebug cloud 实现双 vs code 实例的独立调试会话。

在实际 PHP 开发中，有时需要同时调试两个关联服务（例如前端 API 调用后端微服务），或在多窗口模式下分别调试主应用与管理后台。此时若两个 VS Code 实例都监听默认的 9003 端口，会导致端口冲突或调试会话互相抢占——因为 Xdebug 的 xdebug.client_port 是全局配置项，无法基于 HTTP 请求、域名、路径或环境变量动态变更目标端口。

✅ 正确可行的解决方案如下：

方案一：使用 DBGp Proxy（推荐，原生支持 VS Code）

DBGp Proxy 充当“调试路由中心”，允许多个 IDE 实例注册不同 IDEKEY，再由浏览器扩展或 URL 参数指定目标 IDE：

1. 启动 DBGp Proxy（需 Xdebug 4+）：

   xdebug-proxy --proxy-port=9001 --proxy-host=127.0.0.1

2. 配置两个 VS Code 实例：

   • 实例 A：在 launch.json 中设置 "ideKey": "VSCODE_A"，并启用 pathMappings；
   • 实例 B：设置 "ideKey": "VSCODE_B"；

     ✅ 注意：需使用 vscode-php-debug v1.23+（已支持多 IDE Key 注册）。

3. 触发调试时指定 IDE Key：

   • 安装 Xdebug Helper 浏览器扩展；
   • 右键图标 → “Debug” → 选择 VSCODE_A 或 VSCODE_B；
   • 或手动追加 URL 参数：?XDEBUG_SESSION_START=VSCODE_A

此时 Xdebug 将通过 9001 端口连接到代理，代理根据 IDEKEY 自动转发至对应 VS Code 实例（无需修改 xdebug.client_port）。

方案二：Xdebug Cloud（适合远程/跨网络场景）

• 为每个 VS Code 实例分配唯一 Cloud ID（如 myapp-a / myapp-b）；
• 在浏览器扩展中切换 Cloud ID，或通过 XDEBUG_CLOUD_ID=myapp-a 环境变量启动 PHP；
• ⚠️ 当前限制：VS Code 插件暂不支持 Cloud ID 切换（截至 2025 年），仅 PhpStorm 支持；若坚持使用 VS Code，建议优先采用方案一。

❗重要注意事项

• 不要尝试通过 .htaccess、php.ini 条件加载或多配置文件切换 xdebug.client_port —— Xdebug 在进程启动时即固定该值，运行时不可变；
• 避免手动修改 xdebug.start_with_request 或 xdebug.mode=debug 全局开启，应始终依赖 XDEBUG_SESSION 触发，保障稳定性；
• 调试前务必确认：防火墙放行 9001（代理端口）、各 VS Code 实例未启用 port 冲突的 listen 配置。

通过 DBGp Proxy，你不仅能实现双实例并行调试，还可无缝扩展至 N 个 IDE（如 VS Code + PhpStorm + CLI 调试器共存），是现代 PHP 协作调试的标准实践。