基于php:5.6.40官方镜像的Docker容器Xdebug调试配置问题

我需要为依赖PHP 5.6的旧PHP应用实现调试功能，当前应用运行在基于php:5.6.40官方镜像构建的Docker容器中，服务器地址为192.168.1.182:8100，VS Code主机IP为192.168.1.239。此前在NetBeans中调试时出现无限Socket异常导致无法使用，现切换到VS Code，请问还需进行哪些操作才能使调试功能正常工作？

已配置内容 #

Dockerfile #

FROM php:5.6.40-apache

RUN echo 'deb http://archive.debian.org/debian/ stretch main contrib non-free' > /etc/apt/sources.list
RUN echo 'deb http://archive.debian.org/debian/ stretch-proposed-updates main contrib non-free' >> /etc/apt/sources.list
RUN echo 'deb http://archive.debian.org/debian-security stretch/updates main contrib non-free' >> /etc/apt/sources.list
RUN apt-get update

# Install minimal packages to build Xdebug
 RUN apt-get install -y libpng-dev libzip-dev git
 RUN docker-php-ext-install zip

# Install Xdebug from the source
RUN git clone -b XDEBUG_2_5_5 https://github.com/xdebug/xdebug.git /root/xdebug \
&& cd /root/xdebug && ./rebuild.sh

RUN docker-php-ext-install mysql && docker-php-ext-enable mysql

php.ini的Xdebug配置 #

[xdebug]
zend_extension="xdebug.so"
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=192.168.1.239
xdebug.remote_port=9003
xdebug.idekey="netbeans-xdebug"
xdebug.profiler_output_dir=/var/www/html
xdebug.remote_log="./xdebug.log"
xdebug.show_exception_trace=1

VS Code调试启动配置 #

"configurations": [
    {
        "name": "Listen for Xdebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/var/www/html":"W:/intra/php/intra"
        }, 
        "log": true           
    }
]

• 验证Xdebug安装状态
  进入Docker容器执行php -v，输出必须包含Xdebug v2.5.5标识。如果没有，手动执行docker-php-ext-enable xdebug，并检查./rebuild.sh编译过程是否有报错，确保扩展正确安装到PHP扩展目录。

• 优化Xdebug配置

  1. 将xdebug.remote_mode从req改为jit，避免请求初始化阶段强制建立调试连接，降低Socket异常触发概率；
  2. 修改xdebug.remote_log为绝对路径/var/www/html/xdebug.log，确保日志文件能正常生成，便于排查连接问题；
  3. 把xdebug.idekey改为VSCODE，同时在浏览器安装Xdebug Helper插件，设置IDE Key为VSCODE，调试时激活插件触发调试会话。

• 确认网络与端口可用性

  1. 在容器内执行ping 192.168.1.239，验证VS Code主机的连通性；
  2. 检查VS Code主机的9003端口是否被占用：Windows执行netstat -ano | findstr :9003，Linux/macOS执行lsof -i :9003，若被占用则同步修改Xdebug和VS Code配置中的端口（比如9000）；
  3. 确保VS Code主机防火墙允许9003端口的入站连接，避免拦截Xdebug的调试请求。

• 校验路径映射
  确认pathMappings中的容器路径/var/www/html与实际代码挂载路径完全一致，本地路径W:/intra/php/intra是项目根目录，保证断点文件路径能正确映射到容器内的对应文件。

• 遵循正确调试流程

  1. 在VS Code中启动"Listen for Xdebug"调试会话；
  2. 打开浏览器访问http://192.168.1.182:8100，激活Xdebug Helper插件；
  3. 在VS Code中设置断点，访问对应页面触发断点调试。

• 利用日志排查问题
  查看容器内的/var/www/html/xdebug.log，以及VS Code调试控制台的日志信息，根据日志中的错误提示定位问题，比如连接超时、路径不匹配、权限不足等。

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