多个开发者不能共用同一xdebug.idekey，因Xdebug仅将同key请求路由至首个注册IDE，导致后接入者断点失效或连接被挤占；必须通过DBGp Proxy实现分发，并为每人配置唯一IDE Key及正确路径映射。
为什么多个开发者不能共用同一个 xdebug.idekey
因为 Xdebug 会把所有携带相同 XDEBUG_SESSION_START=PHPSTORM 的请求，全部路由到第一个注册该 key 的 IDE 实例上。后连进来的开发者要么收不到断点，要么被挤掉连接，调试会话直接中断。
根本原因在于：Xdebug 本身不支持多客户端并发监听；它只认一个 idekey + 一个 client_host:port 组合。没有代理层时，这个组合是硬绑定的。
- 每个开发者的浏览器插件（如 Xdebug Helper）必须设独立的 IDE Key，比如
DEV_ALICE、DEV_BOB -
xdebug.idekey在 php.ini 中不能写死成统一值，应设为""或完全删除，交由运行时动态传入 - 必须启用
xdebug.start_with_request=yes（Xdebug 3）或xdebug.remote_autostart=0+ 显式触发（Xdebug 2），避免全量请求都被劫持
必须用 DBGp Proxy，而不是直连模式
直连模式下，Xdebug 只能连一台 IDE；而 dbgpProxy 是唯一能做“请求分发”的中间件——它接收来自 PHP 的调试连接，再根据 cookie 中的 XDEBUG_SESSION_START 值，把请求转发给对应注册过的 IDE。
启动命令示例（Linux/macOS）：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
./pydbgpproxy -d 192.168.1.100:9000 -i 192.168.1.101:9001
其中：
-
-d指向 Web 服务器可访问的地址+端口（即 PHP 的xdebug.client_host/xdebug.remote_host应设为此值） -
-i指向所有开发者机器能访问的地址+端口（PhpStorm / VSCode 配置 DBGP Proxy 时填这里） - 确保防火墙放行
-i端口（如9001），否则 IDE 注册失败
PhpStorm 和 VSCode 的 IDE Key 注册方式差异
两者都走同一套 DBGp Proxy 协议，但注册入口和默认行为不同：
- PhpStorm：菜单栏 Tools → DBGp Proxy → Register IDE，弹窗填
IDE Key、Host、Port；注册后状态栏显示 “DBGp Proxy connected” - VSCode：需安装
PHP Debug插件，并在.vscode/launch.json中配置"pathMappings"和"xdebugSettings": { "max_children": 100 }；IDE Key 由插件自动读取php.ini中的xdebug.idekey或环境变量XDEBUG_IDEKEY - 关键区别：
php.ini中不要设xdebug.idekey，否则 VSCode 会忽略 launch.json 里传的 key；PhpStorm 则以注册窗口为准，不受 php.ini 影响
容易被忽略的路径映射与权限问题
即使 DBGp Proxy 连上了，断点也打不中，大概率是路径没对齐。尤其是 Docker、WAMP/MAMP、符号链接项目这类场景：
- PHP 容器内看到的文件路径（如
/var/www/html/index.php）和本地编辑器打开的路径（如/Users/alice/project/index.php）必须通过pathMappings映射，否则 Xdebug 找不到源码行 - PhpStorm 中：在 Preferences → PHP → Servers 添加服务，勾选
Use path mappings，手动配好远程→本地路径 - VSCode 中：
launch.json的pathMappings必须是对象格式，例如"pathMappings": { "/var/www/html": "${workspaceFolder}" }，不能漏掉引号或写反方向 - 如果用
xdebug.client_host=host.docker.internal（Docker 场景），确认宿主机的/etc/hosts或 Docker 网络配置允许该域名解析
