必须两端同步修改xdebug.client_port和IDE监听端口，如改为9004；用lsof或netstat确认端口占用，重启Apache和IDE，并通过xdebug.log验证连接成功。
直接换端口就行，但必须两端同步改——Xdebug 3.x 不再监听端口，而是主动往外连，它连的目标端口（即 IDE 监听的端口）被占了，就卡在“Waiting for incoming connection…”。
确认谁占了9003
别猜，用命令查真实占用进程：
- macOS/Linux：运行 lsof -i :9003 或 ss -tulpn | grep ':9003'，直接看到进程名和 PID
- Windows：打开 PowerShell，执行 Get-NetTCPConnection -LocalPort 9003 | Select-Object OwningProcess, State，再用 Get-Process -Id <PID> 看是哪个程序
- 常见“嫌疑对象”：另一个 PhpStorm 实例、VS Code 的 PHP Debug 插件、Docker 的 port 映射（如
-p 9003:9003）、甚至酷狗音乐或某些安全软件
两端同步改端口（关键！）
Xdebug 3.x 只认 xdebug.client_port，IDE 必须监听同一个数字，缺一不可：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 修改 php.ini（注意：Web 请求用 Apache 加载的 php.ini，不是 CLI 的）：
xdebug.client_port=9004 - PhpStorm：Settings → PHP → Debug → Xdebug → Debug port 改为 9004，并确保勾选 “Start listening for PHP Debug Connections”
- VS Code：检查
.vscode/launch.json中"port": 9004 - 改完重启 Apache（或 PHP-FPM）和 IDE
验证是否生效
别只看 phpinfo()，要验证系统级连接能力：
- 改完后重启服务，立即运行：
macOS/Linux：lsof -i :9004；Windows：netstat -ano | findstr :9004
有输出，说明 PHP 进程已尝试绑定该端口（其实是发起连接，但 lsof 能捕获到 socket） - 访问页面时打开 xdebug.log（加配置
xdebug.log="/tmp/xdebug.log"），日志里出现Connection to '127.0.0.1:9004' succeeded才算真正通了 - 如果仍失败，检查防火墙是否放行本地回环（127.0.0.1）的该端口
避免反复踩坑的小提醒
很多问题其实源于配置残留或路径错位：
- 别再写
xdebug.remote_port——Xdebug 3.x 已废弃，写了也不报错，但等于没配 - 确认你改的是实际生效的 php.ini：运行
php --ini或看 phpinfo() 里的 “Loaded Configuration File” - CLI 和 Web 用的不是同一个 php.ini，调试网页请求一定要改 Apache 对应的那个
- 端口选 9004、9005、9009 都可以，但尽量避开 9000（PHP-FPM 默认）、9001（DBGp Proxy 常用）、9003（太热门容易冲突）
