Xdebug 3 client_host与client_port详解

Xdebug 3 的调试连接完全依赖于 `xdebug.client_host` 和 `xdebug.client_port` 这一对关键配置：前者指定 IDE 所在机器的可访问 IP（不是 Xdebug 自身地址，而是它“主动去找谁”），后者指定 IDE 实际监听的端口（不是 Xdebug 开放的端口，而是它“拨号打给哪”），二者共同构成唯一的出站连接目标；配置错误不会报错，却会导致断点失效、IDE 静默等待或页面卡顿等疑难问题，尤其在 Docker 环境中将 `client_host` 误设为 `127.0.0.1`（容器内指向自身）、或沿用 Xdebug 2 的 `9000` 端口（Xdebug 3 默认且必须为 `9003`）是高频踩坑点，务必通过 `telnet`/`nc` 实测连通性，并结合 `xdebug.log` 中的连接失败记录精准定位——真正的调试稳定性，始于对这两个参数语义的彻底厘清。

client_host 是 Xdebug 找谁连，不是“它在哪”

xdebug.client_host 指的是 IDE（比如 VSCode、PhpStorm）正在监听调试连接的那台机器的 IP 地址。Xdebug 会主动往这个地址发连接请求，而不是等 IDE 来找它。

常见误区是把它当成“Xdebug 自己的地址”，结果填成 127.0.0.1 却在 Docker 容器里跑 PHP —— 这时容器里的 127.0.0.1 指的是容器自己，根本连不到宿主机上的 IDE。

• 本地开发（PHP 和 IDE 都在本机）：填 127.0.0.1 或 localhost
• Docker 环境：优先用 host.docker.internal（Docker Desktop 默认支持），Windows/Linux 上若不生效可改用宿主机真实 IP（如 192.168.1.100）
• 远程服务器 + 本地 IDE：必须填你本机可被服务器路由到的公网或内网 IP，不能填 localhost
• 别依赖 DNS 解析慢的主机名；有延迟就直接填 IP

client_port 是 Xdebug 往哪端口拨号，不是“它开哪个口”

xdebug.client_port 是 Xdebug 尝试连接的目标端口，也就是你的 IDE 调试监听器实际打开的端口。它和 Xdebug 自己“监听什么端口”完全无关 —— Xdebug 在 3.x 中不再监听，只 outbound 连接。

默认值是 9003，这是 Xdebug 3 的硬编码约定，和 Xdebug 2 的 9000 不兼容。如果你的 IDE 配置里写的是 9000，断点必然不触发。

• VSCode 的 launch.json 里 "port": 9003 必须和 xdebug.client_port = 9003 严格一致
• 多个项目共用一个 IDE？可以都设成 9003，只要不同时启动两个“Listen for Xdebug”任务
• 端口被占用？改 IDE 配置和 xdebug.client_port 成同一新值（如 9050），别只改一半
• 别再写 xdebug.remote_port —— 这个参数在 Xdebug 3 中已彻底失效，写了也不报错，但等于白配

connect_timeout_ms 决定“连不上时卡多久”

即使 xdebug.start_with_request = trigger，Xdebug 在某些错误场景下仍可能尝试连接 IDE。如果 xdebug.client_host 不可达、xdebug.client_port 没监听，Xdebug 会卡住等响应，直到超时。

这个等待时间由 xdebug.connect_timeout_ms 控制，默认 200（毫秒）。设为 0 风险极大：部分版本会解释为“无限等待”，导致页面直接超时。

• 开发环境建议保持默认或略调高（如 500），便于发现连接问题
• 生产环境必须禁用调试（xdebug.mode = off），否则哪怕只配了 client_host 和 client_port，也存在隐式连接尝试风险
• 配合 xdebug.log 查日志时，第一眼就看有没有 “Failed to connect to client host” 类错误

client_host/client_port 配不匹配的典型症状

配置错位不会报错，只会让调试静默失效，排查起来最费时间。

典型现象包括：断点灰色不可用、IDE 显示 “waiting for Xdebug session” 但无响应、页面加载明显变慢（尤其报错时）、xdebug.log 里反复出现连接拒绝或超时记录。

• 先确认 php -v 输出含 Xdebug 版本信息，排除扩展未加载
• 再检查 phpinfo() 页面中 xdebug.client_host 和 xdebug.client_port 的值是否和 IDE 实际监听一致
• 用 telnet 127.0.0.1 9003（或 nc -zv 127.0.0.1 9003）测试 IDE 是否真在监听该端口
• Docker 场景务必验证 host.docker.internal 能否从容器内 ping 通、端口是否开放（curl http://host.docker.internal:9003 会失败，但 telnet 应能连上）

Xdebug 3 的网络模型是单向出站，client_host 和 client_port 构成唯一出口地址。任何想当然的“应该能通”都得拿 telnet 和 xdebug.log 验证——尤其在容器、代理、多网卡环境下，IP 和端口的语义很容易被绕晕。

理论要掌握，实操不能落！以上关于《Xdebug 3 client_host与client_port详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！