connection refused 表明xdebug尝试连接的ip:端口无进程监听，或被防火墙/docker网络拦截；需先开启xdebug.log_level=10和xdebug.log=/tmp/xdebug.log查日志，确认是否出现“connecting to”及后续错误，再验证ide监听状态、防火墙策略与路径映射。
Connection refused 不是代码问题，而是网络链路在“敲门”时发现没人应答。核心就两点：Xdebug 试图连的地址端口，IDE 确实没在那儿监听；或者中间有防火墙、Docker 网络、主机绑定策略把它拦下了。
看日志确认 Xdebug 是否真在尝试连接
先打开 Xdebug 日志，这是所有排查的起点：
- 在 php.ini 中加两行：xdebug.log_level=10 和 xdebug.log=/tmp/xdebug.log（确保 PHP 进程有写权限）
- 重启 PHP 服务（如
sudo systemctl restart php8.1-fpm） - 触发一次请求（比如带
?XDEBUG_SESSION_START=1的 URL），再查日志
如果日志里压根没有 “Connecting to configured address”，说明 Xdebug 根本没启动调试——检查 xdebug.mode=debug 和 xdebug.start_with_request=trigger（或 yes）是否生效；如果看到 “Connecting to …” 但紧跟着 “Could not connect to client”，说明它动了，只是连不上。
确认 IDE 是否真在监听指定端口
Connection refused 的本质是：TCP 包发到了目标 IP:Port，但该端口上没有任何进程 accept 连接。验证方法很直接：
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 在 IDE 启动调试监听后，执行：
ss -tln | grep 9003（Linux）或netstat -an | findstr :9003（Windows） - 若无输出，说明 IDE 没监听，或监听地址不对（比如只绑定了
127.0.0.1，而 Xdebug 从192.168.1.100发起连接） - VSCode 用户请核对
launch.json中port是否为9003，且与xdebug.client_port完全一致
常见陷阱：PhpStorm 默认监听 127.0.0.1:9003，若 Xdebug 运行在 Docker 容器内，client_host 却设成 localhost，实际会解析为容器自己的 127.0.0.1，而非宿主机——此时应设为宿主机网关 IP（如 172.17.0.1）或启用 host.docker.internal。
查防火墙、安全组与 Docker 网络
即使 IDE 监听了，也可能被中间层拦截：
- 本地防火墙：
sudo ufw status（Ubuntu）或sudo firewall-cmd --state（CentOS），确认 9003 端口入站放行 - 云服务器安全组：检查是否允许来自你开发机 IP 的 TCP 9003 入向规则
- Docker 场景：
docker run启动容器时必须加-p 9003:9003，且容器内 Xdebug 的client_host要指向宿主机（不是localhost） - Mac M1/M2 用户注意：Docker Desktop 的
host.docker.internal在某些版本下不自动解析，可临时改用10.0.2.2或宿主机真实 IP
调参绕过常见超时与 DNS 卡顿
局域网都可能因配置太激进而失败：
- xdebug.connect_timeout_ms=5000：默认仅 200ms，远程或虚拟机环境极易超时
-
xdebug.discover_client_host=0：关闭自动探测，强制使用你写的
client_host，避免日志里反复出现getaddrinfo查询拖慢启动 - 路径映射错也会表现为“连上即断”：日志中若见
Resolved path mapping for /var/www/html/...但本地路径对不上，说明 IDE 的服务器路径映射配置错误，需在 Settings → PHP → Servers 中核对绝对路径
不复杂但容易忽略
