Xdebug未连接的根本原因是PHP进程未发起调试连接，主因是xdebug.mode未设为debug或xdebug.start_with_request=yes未启用；需验证配置加载顺序、client_host填本地IP而非localhost、端口为9003且防火墙放行。
IDE显示“等待连接”但Xdebug没反应
这说明Xdebug根本没连出去，不是IDE没收到，而是PHP进程压根没发起连接。最常见原因是xdebug.mode没设对或配置被覆盖。
检查点：
- 确保xdebug.mode=debug（不是develop或空值）
- xdebug.start_with_request=yes必须显式开启，否则只靠GET参数XDEBUG_SESSION_START触发不可靠
- 运行php -v确认Xdebug已加载；再执行php --ri xdebug看输出里mode是否为debug
- 多个.ini文件时，用php --ini查加载顺序，后加载的会覆盖前面的设置
xdebug.client_host配置成localhost就失败
这是远程调试最典型的坑：Xdebug运行在服务器上，它要主动连你的IDE，所以xdebug.client_host必须填你本地机器的IP（比如192.168.1.100），不能写localhost或127.0.0.1——那会让Xdebug去连服务器自己。
特殊情况处理：
- Docker环境用host.docker.internal（Docker Desktop）或宿主机网关IP（Linux需手动查）
- WSL2下xdebug.client_host填Windows主机IP，且确保Windows防火墙放行9003端口
- 如果IDE和PHP在同一台机器（本地开发），才可用127.0.0.1
连接超时、断点不生效、频繁断开
这些现象背后常是路径映射或超时参数问题，不是网络不通。
Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有
排查重点：
- 断点无效？检查IDE里的“服务器路径映射”，确保PHP脚本的绝对路径（如/var/www/html/index.php）正确映射到你本地项目路径（如/Users/me/project）
- 连接超时？调大xdebug.connect_timeout_ms（默认200ms太短），设为5000更稳妥
- 频繁断开？加xdebug.discover_client_host=0禁用自动发现，避免DNS干扰
- 启用日志：xdebug.log=/tmp/xdebug.log + xdebug.log_level=10，看日志里有没有Connecting to configured address/port或Connection refused
防火墙/SELinux/端口冲突拦住了连接
Xdebug默认走9003端口（Xdebug 3+），但很多教程还按老版本写9000，容易撞上PHP-FPM监听端口，导致连上的是FPM而不是IDE。
动作清单：
- 在IDE里确认监听端口是9003（PhpStorm：Settings → PHP → Debug → Xdebug → Debug port）
- Linux服务器执行ss -tuln | grep ':9003'，确认没其他进程占着
- 关闭防火墙临时测试：sudo ufw disable（Ubuntu）或sudo systemctl stop firewalld（CentOS）
- SELinux用户加规则：sudo setsebool -P httpd_can_network_connect 1（允许Apache/FPM外连）
实际调试时最容易忽略的是xdebug.mode和xdebug.start_with_request这两个开关是否真正生效，而不是只改了某个.ini文件却没被PHP加载。每次改完务必用php --ri xdebug验证，别凭感觉。
