xdebug.client_host是ide监听地址，xdebug.client_port是ide监听端口，二者共同构成xdebug出站连接目标；默认端口9003，client_host在docker中需设宿主机ip而非127.0.0.1。
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，断点必然不触发。
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
- 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应能连上）
client_host 和 client_port 构成唯一出口地址。任何想当然的“应该能通”都得拿 telnet 和 xdebug.log 验证——尤其在容器、代理、多网卡环境下，IP 和端口的语义很容易被绕晕。
