PhpStorm监听端口与xdebug.client_port必须严格一致，否则Xdebug无法连接；需同步配置、确认生效、排查端口占用及client_host地址，三者任一错误均导致静默失败。
phpstorm监听端口和xdebug.client_port必须一致
PHPStorm 不是“连接 Xdebug”，而是被动等待 Xdebug 主动连过来。所以它监听的端口，必须和 xdebug.client_port 完全一样，否则连接直接失败，连日志都可能不生成。
常见错误是：PHPStorm 默认监听 9003，但 xdebug.client_port 还留着旧习惯设成 9000；或者反过来，改了 xdebug.client_port 却忘了在 PHPStorm 的 Settings → PHP → Debug → Xdebug → Debug port 里同步修改。
- 打开 PHPStorm 的
Settings → PHP → Debug，确认Debug port值（比如9003） - 检查 php.ini 或 xdebug.ini 中是否设置了
xdebug.client_port=9003（Xdebug 3）或xdebug.remote_port=9003（Xdebug 2） - 运行
php --ri xdebug或查看phpinfo()输出，确认该配置项实际生效值 - 别信“默认就是 9003”——Xdebug 3 默认确实是
9003，但很多旧配置残留会覆盖它
本地 9003 端口被其他进程占用了
即使 PHPStorm 和 Xdebug 都配成了 9003，如果这个端口正被酷狗、QQ、VS Code、另一个 PHPStorm 实例甚至 Docker 容器里的服务占着，Xdebug 就会连接失败，PHPStorm 一直显示 “Waiting for incoming connection…”。
Windows 下快速检查：netstat -ano | findstr :9003，看 PID 对应什么程序；macOS/Linux 用：lsof -i :9003 或 ss -tuln | grep :9003。
立即学习“PHP免费学习笔记（深入）”；
- 杀掉占用进程，或换一个端口（比如
9004），两端同步改 - 避免用
9000—— PHP-FPM 默认监听它，远程服务器上极易冲突 - 改完端口后，重启 Web 服务（如 Apache/Nginx + PHP-FPM）和 PHPStorm，仅重载配置不够
Docker 或 WSL 环境下 client_host 配置错成 localhost
在容器或 WSL 里跑 PHP，xdebug.client_host=localhost 是最典型的“伪成功”陷阱：Xdebug 看似连上了，日志里写 Connected to client，但连的是容器/WSL 自己的回环，不是宿主机上的 PHPStorm。
正确做法取决于环境：
- Docker Desktop（macOS/Windows）：用
xdebug.client_host=host.docker.internal - Linux Docker：用宿主机真实 IP（如
172.17.0.1），或加--add-host=host.docker.internal:host-gateway - WSL2：用 Windows 主机 IP（查
cat /etc/resolv.conf中的nameserver），不是localhost - 别开
xdebug.discover_client_host=1或xdebug.remote_connect_back=1—— 安全风险高，且在多数 NAT 环境下根本不可靠
断点不触发？先确认 xdebug.mode 和触发方式是否匹配
Xdebug 3 彻底废弃了 xdebug.remote_enable，只认 xdebug.mode。设成 off 或漏配，整个调试链就断在第一步，压根不会尝试连 PHPStorm。
- 必须有
xdebug.mode=debug（最低要求），可追加develop方便开发时显示堆栈 -
xdebug.start_with_request=yes会强制所有请求都连 IDE，适合本地开发；线上千万别开 - 更安全的触发方式是
xdebug.start_with_request=trigger+ 浏览器插件（Xdebug Helper）或 URL 加?XDEBUG_SESSION_START=1 - 检查
phpinfo()页面里xdebug.mode行，值必须是debug，不是空、off或拼错成debog
