Xdebug多项目不能共用client_port，因Xdebug 3默认仅允许单连接绑定同一端口，后发起的调试请求被静默丢弃；须为各项目配置唯一xdebug.idekey和独立xdebug.client_port，并在PHPStorm运行配置中严格匹配。
不能共用端口——Xdebug 3 默认只允许一个调试连接绑定到同一端口，多项目共用会导致后发起的调试请求被静默丢弃，表现为断点不触发、PHPStorm 无响应。
为什么 Xdebug 多项目不能共用 client_port
Xdebug 启动调试会话时，会主动向 xdebug.client_host 和 xdebug.client_port 发起 TCP 连接。PHPStorm 的 “Listen for PHP Debug Connections” 是一个单监听 socket，同一端口无法同时接受多个并发连接（除非启用代理模式）。即使你看到两个项目都“连上了”，实际只有第一个成功握手的会话能持续通信。
常见错误现象包括：
- 项目 A 能断点，项目 B 刷新页面后 PHPStorm 完全无日志、无弹窗、无堆栈
- PHPStorm 底部状态栏显示 “Waiting for connection…”，但始终不进入调试上下文
-
phpinfo()显示 Xdebug 已加载，netstat -an | grep 9003却看不到 ESTABLISHED 连接
正确做法：用 IDE Key + 端口分离双保险
必须同时满足两个条件才能稳定支持多项目调试：
立即学习“PHP免费学习笔记（深入）”；
- 每个项目在
php.ini或.user.ini中设置唯一的xdebug.idekey（如LARAVEL_DEV、WP_LOCAL） - 每个项目配置独立的
xdebug.client_port（如9009、9010、9011），并在 PHPStorm 对应的 Run Configuration 中匹配该端口 - PHPStorm 的
Run → Edit Configurations → PHP Web Page中，勾选Filter debug connection by IDE key，并填入对应项目的idekey - 若使用 Docker，确保
php.ini修改在容器内生效（docker exec -it php-container cat /usr/local/etc/php/php.ini验证）
示例（Laravel 项目）：
;; 在容器或本地 php.ini 中 [xdebug] zend_extension=xdebug.so xdebug.mode=debug xdebug.client_host=127.0.0.1 xdebug.client_port=9009 xdebug.start_with_request=yes xdebug.idekey=LARAVEL_DEV
对应 PHPStorm 配置中，“IDE Key” 填 LARAVEL_DEV，“Debug port” 填 9009。
容易被忽略的兼容性细节
Xdebug 3.x 与 2.x 的配置项不兼容，混用会导致静默失效：
-
xdebug.remote_port（2.x）和xdebug.client_port（3.x）不能共存；若 php.ini 同时出现两者，Xdebug 3 会忽略remote_*系列 -
xdebug.start_with_request=yes比xdebug.remote_autostart=1更可靠，后者在 CLI 场景下行为不稳定 -
xdebug.client_port必须是整数类型，写成"9009"（带引号）会被 Xdebug 忽略，且不报错 - PHPStorm 的 Debug Port 设置（
Settings → PHP → Debug）仅控制 IDE 自身监听端口，不影响 Xdebug 主动连接行为；它只对 “PHP Script” 类型运行配置起作用，Web 调试依赖的是 Run Configuration 中的端口和 IDE Key
真正决定能否调试成功的，是 xdebug.idekey 和 PHPStorm Run Configuration 中的 IDE Key 是否完全一致、xdebug.client_port 与 Run Configuration 中指定的端口是否匹配、以及该端口未被其他进程占用——三者缺一不可。端口冲突是最隐蔽的卡点，建议用 lsof -i :9009（macOS/Linux）或 netstat -ano | findstr :9009（Windows）提前验证。
