Xdebug 3.x默认9003端口被占用怎么办？快速换端口指南【方法】-php教程-PHP中文网

必须两端同步修改xdebug.client_port和ide监听端口，如改为9004；用lsof或netstat确认端口占用，重启apache和ide，并通过xdebug.log验证连接成功。

xdebug 3.x默认9003端口被占用怎么办？快速换端口指南【方法】

直接换端口就行，但必须两端同步改——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 看是哪个程序
常见“嫌疑对象”：另一个 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）的该端口