Xdebug远程调试必须满足三条件：扩展成功加载、远程连接参数准确、网络端口可达；需通过php -m、php --ini和phpinfo()交叉验证CLI与Web SAPI配置一致，严格区分Xdebug 2/3配置项（如xdebug.mode=debug替代remote_enable），并确保xdebug.start_with_request=trigger或yes启用调试通道。
远程调试 PHP 时，xdebug 在服务器端的配置必须满足三个硬性条件：扩展加载成功、远程连接参数准确、网络端口可达。缺一不可，否则 PhpStorm 永远收不到断点请求。
如何确认 xdebug 扩展已正确加载
别只看 phpinfo() 页面有没有 Xdebug 区块——那只是扩展存在，不等于启用。真正要验证的是 CLI 和 Web SAPI 是否都加载了同一个 zend_extension：
- 执行
php -m | grep xdebug，输出应为xdebug（小写，无空格） - 执行
php --ini查看实际生效的php.ini路径，再用grep -i "zend_extension.*xdebug" /path/to/php.ini确认路径指向的是.so（Linux/macOS）或.dll（Windows）文件，且未被注释 - 在 Web 环境中访问
phpinfo()，搜索Loaded Configuration File，确保它和 CLI 显示的一致；若不一致，说明 FPM/Apache 使用了另一份配置，需单独修改 - 常见坑：
zend_extension写成extension=xdebug.so（Xdebug 3+ 不支持）、路径含中文或空格未加引号、扩展文件权限为 root 但 php-fpm 以 www-data 运行导致无法读取
Xdebug 2 与 Xdebug 3 的关键配置差异
版本混淆是远程调试失败最隐蔽的原因。Xdebug 3 彻底重命名了大量配置项，旧配置在新版中完全失效：
-
xdebug.remote_enable→xdebug.mode=debug（Xdebug 3 必须显式设为debug，off或develop都不行） -
xdebug.remote_host→xdebug.client_host（注意不是server_host） -
xdebug.remote_port→xdebug.client_port -
xdebug.idekey仍有效，但 Xdebug 3 默认值为PHPSTORM，可省略 - Xdebug 3 强制要求
xdebug.start_with_request=trigger或yes，否则即使mode=debug也不会监听——这是比 Xdebug 2 多出的关键开关
为什么开了 xdebug.mode=debug 却没连上 PhpStorm
绝大多数情况不是配置写错，而是网络链路被拦在中间。按顺序排查：
立即学习“PHP免费学习笔记（深入）”；
- 服务器防火墙是否放行
xdebug.client_port（默认 9003，非 9000）？执行ss -tlnp | grep :9003看端口是否处于LISTEN状态 - 如果服务器在 Docker 容器内，宿主机的
docker run命令是否加了-p 9003:9003？容器内部xdebug.client_host应设为宿主机 IP（如172.17.0.1），而非localhost - 若走 SSH 端口转发（如
ssh -R 9003:127.0.0.1:9003 user@host），需确认GatewayPorts yes已在服务端/etc/ssh/sshd_config中启用，否则转发仅限本地回环 - PhpStorm 的
Settings > PHP > Servers中，Host必须填服务器对外可访问的域名/IP，不能填localhost；Path mappings的远程路径必须与服务器上$_SERVER['DOCUMENT_ROOT']完全一致（末尾斜杠敏感）
多用户共用一台调试服务器时的必选项
当多个开发者同时调试同一套线上代码，xdebug.client_host 无法指向多个 IP，必须引入 dbgpProxy：
- 下载对应平台的
dbgpProxy（非 Xdebug 自带，需单独获取），在服务器上运行：./dbgpProxy -i 0.0.0.0:9001 -s 0.0.0.0:9003（前者供 PhpStorm 连接，后者供 Xdebug 连接） - 每个 PhpStorm 配置
Settings > PHP > Debug > DBGp Proxy，IDE key设为唯一标识（如alice、bob），Host和Port填代理地址（即-i参数值） - 服务器端 Xdebug 配置改为：
xdebug.client_host=127.0.0.1、xdebug.client_port=9003（指向代理的-s端口） - 关键细节：代理启动后，Xdebug 日志（
xdebug.log）里会显示连接目标变成127.0.0.1:9003，而非 PhpStorm 的 IP；若仍尝试直连 PhpStorm，说明代理未生效或 Xdebug 配置未重载
最容易被忽略的是 Xdebug 3 的 xdebug.start_with_request 和 xdebug.mode 的组合逻辑——只设 mode=debug 不够，必须配合触发方式，否则整个调试通道是关闭的。这点在升级 Xdebug 后几乎必然踩坑。
