现象
PhpStorm 里点了监听,浏览器访问项目页面,断点始终不命中。Xdebug 日志里反复出现 Connecting to 127.0.0.1:9003 后接 Timeout,页面本身能正常返回。本机直接跑 PHP 时偶尔能连上,换成 Docker 或 WSL 就完全不行。
原因
Xdebug 3 默认 CLIent_port 是 9003,client_host 是 127.0.0.1。请求从容器或虚拟机发出时,127.0.0.1 指向的是容器自己,不是运行 IDE 的宿主机,连接自然超时。另一个常见原因是 xdebug.mode 里没有开 debug,或者 start_with_request 设为 trigger 但请求没带触发参数。
解决步骤
第一步,确认 Xdebug 的加载状态。输出 xdebug_info() 页面或用命令行查看版本和模式,确认 mode 包含 debug、client_port 是 9003。
php -i | grep -E 'xdebug.mode|xdebug.client_host|xdebug.client_port'
php -r "var_dump(extension_loaded('xdebug'));"
第二步,把 client_host 指向宿主机。在 php.ini 或 99-xdebug.ini 里写死宿主机可达 IP,容器场景可用 host.docker.internal,同时打开日志方便排查。
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=192.168.1.20
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
第三步,放行端口并重启。确认宿主机防火墙允许 9003 入站,IDE 监听的是 0.0.0.0 而不是仅回环;Docker 场景要确认容器网络能访问宿主机地址,改完重启 FPM 再试。
验证
访问页面后 /tmp/xdebug.log 出现 Connected to 192.168.1.20:9003,IDE 在断点处停下并能查看变量,说明链路打通。
小结
9003 连不上多半是 client_host 在容器里指错了地址。先确认 mode,再把 host 改到宿主机并放行端口,最后看日志确认连接成功。
