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：
-
启动 DBGp Proxy（需 Xdebug 4+）：
HISUI 前端框架开发指南（IRIS版）下载HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
xdebug-proxy --proxy-port=9001 --proxy-host=127.0.0.1
-
配置两个 VS Code 实例：
- 实例 A：在 launch.json 中设置 "ideKey": "VSCODE_A"，并启用 pathMappings；
- 实例 B：设置 "ideKey": "VSCODE_B"；
✅ 注意：需使用 vscode-php-debug v1.23+（已支持多 IDE Key 注册）。
-
触发调试时指定 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 切换（截至 2024 年），仅 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 协作调试的标准实践。
