PHP 7.1搭配Xdebug 2与PhpStorm调试失败问题求助

问题描述 #

使用PHP 7.1搭配Xdebug 2.9.8与PhpStorm调试时，IDE无法识别调试会话。已配置PhpStorm服务器及路径映射，但问题依旧；切换至PHP 7.2 + Xdebug 3.1.6时调试功能正常。

当前Xdebug 2.9.8配置（xdebug.ini） #

zend_extension=xdebug.so
xdebug.remote_enable=on
xdebug.remote_autostart=off
xdebug.remote_connect_back=off
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.remote_host=host.docker.internal
xdebug.remote_mode=req
xdebug.idekey=PHPSTORM
xdebug.extended_info=on

Dockerfile配置 #

FROM php:7.1-fpm
RUN apt-get update && apt-get install -y libc-client-dev libpng-dev libjpeg-dev libxml2-dev libkrb5-dev wget && rm -r /var/lib/apt/lists/*
RUN docker-php-ext-configure imap --with-kerberos --with-imap-ssl\
    && docker-php-ext-install gettext soap imap pdo_mysql exif zip gd \
    && pecl install xdebug-2.9.8  \
    && docker-php-ext-enable xdebug;

Xdebug 3.1.6可用配置（对比参考） #

[xdebug]
zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log_level=0
xdebug.idekey=PHPSTORM

问题原因及解决方案 #

以下是核心原因及对应排查方向：

1. 端口冲突：Xdebug 2与PHP-FPM默认端口重叠
   PHP-FPM默认监听9000端口，你配置的Xdebug 2也使用remote_port=9000，导致Xdebug无法正常绑定端口发起调试连接。Xdebug 3默认使用9003端口，避开了这个冲突，因此能正常工作。

• 解决方案：将Xdebug 2的remote_port改为9003，同时在PhpStorm的「Settings > Languages & Frameworks > PHP > Debug」中，将调试端口同步改为9003。

2. 调试触发方式差异
   Xdebug 2配置了remote_autostart=off，意味着需要手动触发调试会话（比如通过浏览器插件设置XDEBUG_SESSION=PHPSTORM，或在请求URL后追加?XDEBUG_SESSION_START=PHPSTORM参数）；而Xdebug 3的start_with_request=yes会自动启动调试会话。若未手动触发，Xdebug 2不会主动向PhpStorm发起连接。

• 解决方案：开启xdebug.remote_autostart=on，或手动添加调试触发参数。

3. host.docker.internal兼容性问题
   部分旧版本Docker（尤其是Linux平台早期版本）不支持host.docker.internal域名解析，PHP 7.1的基础镜像可能搭配的Docker环境版本较低，导致Xdebug 2无法解析该主机名。而PHP 7.2的镜像使用了更新的环境，支持该域名。

• 解决方案：将remote_host替换为宿主机的实际IP地址（如192.168.1.100），确保容器能访问到宿主机的PhpStorm调试端口。

4. remote_mode设置导致的连接失败
   Xdebug 2的remote_mode=req要求脚本执行前必须成功连接到IDE，否则会跳过调试甚至卡住。而Xdebug 3的调试模式更灵活，不会强制阻塞脚本。

• 解决方案：将remote_mode改为jit，仅在遇到断点时发起连接，降低连接失败的影响。

5. Xdebug扩展加载验证
   进入容器执行php -m或生成phpinfo()页面，确认Xdebug扩展已被正确加载。旧版本PHP镜像中，docker-php-ext-enable可能存在缓存或路径问题，导致扩展未生效。

• 解决方案：若未加载，可尝试在Dockerfile中手动指定扩展路径，或重启容器重新加载配置。

内容的提问来源于stack exchange，提问作者Dariusz Rup