xdebug 报 address already in use，根本原因不是配置错误，而是 9003（或自定义的 xdebug.client_port）端口被其他进程占用或残留 time_wait 状态；需用 ss/lsof（linux/macos）或 get-nettcpconnection（windows）精准定位并清理占用进程，同时确认 xdebug 是否真正启动监听（如 start_with_request=trigger 时可能未监听）。
直接说结论：Xdebug 报 Address already in use，基本不是 Xdebug 自身配置错，而是端口被其他进程占了，或者上一次调试会话没彻底退出、残留监听。重点查 9003（Xdebug 3 默认端口）或你自定义的 xdebug.client_port 值是否真空闲。
确认 Xdebug 实际监听哪个端口
Xdebug 3 默认用 9003，但如果你改过 xdebug.client_port 或用了旧版（Xdebug 2 是 9000），就得按实际值查。别凭印象猜。
- 检查 php.ini 中是否显式设置了
xdebug.client_port=9003（或别的值） - 运行
php --ri xdebug，看输出里client_port行显示的数值 - 如果用的是 Docker 或远程调试，还要确认宿主机/容器网络配置是否做了端口映射，比如
-p 9003:9003是否重复绑定
Linux/macOS 下快速定位占用 9003 的进程
别用 netstat（部分新版系统已弃用），优先用 ss 或 lsof：
Xdebug 3.4.1
下载
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
-
ss -tulpn | grep ':9003'—— 显示监听该端口的进程名和 PID -
lsof -i :9003—— 更直观，直接列出进程路径（macOS 需装lsof；Linux 通常自带） - 常见“假想敌”：
phpstorm自带的 DBGp proxy、旧的php -S服务、另一个 PHP-FPM 子进程、甚至 VS Code 的 PHP Debug 插件残留 socket
Windows 下查 9003 谁在用
PowerShell 比 cmd 更可靠：
Get-NetTCPConnection -LocalPort 9003 | Select-Object OwningProcess, State- 拿到
OwningProcess（PID）后，再执行：Get-Process -Id <pid></pid>看进程名 - 注意：Windows 上某些安全软件或 Hyper-V 虚拟交换机可能静默占用高编号端口，若查不到具体进程，可临时禁用防火墙/杀软测试
为什么 kill 掉进程后还报错？TIME_WAIT 是元凶
即使你干掉了占用进程，9003 可能仍不可用，因为 TCP 连接处于 TIME_WAIT 状态（默认持续 2×MSL ≈ 60–120 秒）。这不是 bug，是 TCP 协议保证可靠性的设计。
- Xdebug 启动时若发现端口处于
TIME_WAIT，仍会报Address already in use - 临时解法：等 2 分钟再试；或加
SO_REUSEADDR（但 Xdebug 不暴露这个开关） - 根治思路：避免频繁重启调试器；改用不同端口轮换（如
9004,9005）；或确保 IDE 正常断开调试连接（而非直接关窗口）
最容易被忽略的一点：Xdebug 的 xdebug.start_with_request 设为 trigger 时，IDE 断点未触发，Xdebug 就不会真正监听端口——所以报错时先确认你是不是误以为它该监听，其实根本没启动监听逻辑。
