PHPStorm调试端口默认9003，若被占用需同步修改PHPStorm的Debug port和Xdebug的xdebug.client_port（Xdebug 3）或xdebug.remote_port（Xdebug 2）为同一非冲突端口（如9009），并确保IDE Key、php.ini路径、浏览器插件设置完全一致，最后重启PHP服务与PHPStorm。
PHPStorm 调试端口默认是 9003，但和 Xdebug 冲突时必须改
PHPStorm 默认监听 9003 端口接收 Xdebug 连接，但如果你本地已运行了另一个 PHP-FPM、旧版 Xdebug（如 2.x）或其它调试服务占用了该端口，就会出现「Connection refused」或断点不触发。此时不能只改 PHPStorm 设置，必须同步调整 Xdebug 配置中的 xddebug.client_port（Xdebug 3+）或 xddebug.remote_port（Xdebug 2），否则调试器根本连不上。
- 检查端口是否被占用：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - 推荐改用非冲突端口，例如
9009，避免和常见服务（如 FastCGI、旧 Xdebug）撞车 - PHPStorm 中修改路径：Settings → PHP → Debug → Xdebug → Debug port，填入新端口号（如
9009）
修改 php.ini 中的 xdebug.client_port 必须与 PHPStorm 一致
Xdebug 3 要求 xddebug.client_port 和 PHPStorm 的 Debug port 完全匹配，否则连接会静默失败——没有报错，但断点不生效、$_SERVER['HTTP_X_DEBUGGER'] 不出现、IDE key 也不识别。
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=PHPSTORM
- 确认你编辑的是当前 PHP CLI 和 Web Server 实际加载的
php.ini（用php --ini和phpinfo()验证） - 如果使用 Docker，
php.ini在容器内，不能只改宿主机文件 -
xdebug.client_port是整数，不要加引号；若写成"9009"，Xdebug 会忽略该配置
多项目共存时，不同项目要用不同调试端口防冲突
当你同时跑多个本地 PHP 项目（比如 Laravel + WordPress），且都启用了 Xdebug，它们若共用一个调试端口，PHPStorm 只能响应其中一个连接，其余请求会被丢弃——表现为某个项目能调试，另一个完全无反应。
- 为每个项目单独配置：在 PHPStorm 的 Run → Edit Configurations → PHP Web Page / PHP Script 中，勾选 Filter debug connection by IDE key，并设置唯一
IDE KEY（如LARAVEL_DEV、WP_LOCAL） - 对应在各项目的
php.ini或.user.ini中设置xdebug.idekey，并与 PHPStorm 中的 IDE key 严格一致 - 端口可统一（如都用
9009），但更稳妥的做法是按项目分配端口（9009、9010、9011），并在各自服务器配置中指定xdebug.client_port
浏览器插件和 Xdebug Helper 的 IDE Key 必须匹配 PHPStorm 设置
即使端口和 php.ini 全对，如果浏览器点击「Debug」后没触发，大概率是 IDE Key 不一致。Xdebug Helper 插件发送的 XDEBUG_SESSION_START=PHPSTORM 请求头，必须和 PHPStorm 的 idekey 值完全相同（大小写敏感）。
立即学习“PHP免费学习笔记（深入）”；
- PHPStorm 默认 IDE Key 是
PHPSTORM，可在 Settings → PHP → Debug → Xdebug → IDE key 修改 - 浏览器插件里也要手动设成一样，不能依赖「自动检测」
- 验证方式：在 PHP 脚本中打印
$_SERVER['XDEBUG_SESSION']，应输出你设定的 IDE Key 值 - 如果用了 Nginx/Apache 的
fastcgi_param或SetEnv强制传递XDEBUG_SESSION，也要确保值一致
