Docker容器中PHP5.6+xdebug2.5.5在VSCode调试断点未触发求助

• 解决配置冲突：Xdebug 2.5 中xdebug.remote_connect_back=1会优先于xdebug.remote_host生效，导致后者被忽略。直接关闭remote_connect_back，仅保留remote_host配置，示例：

  xdebug.remote_enable=1
  xdebug.remote_connect_back=0
  xdebug.remote_host=宿主机实际IP或host.docker.internal
  xdebug.remote_port=9001
  xdebug.idekey="VSC"
  xdebug.remote_log=/tmp/x_debug.log
  zend_extension=xdebug.so
  

• 验证宿主机地址可达性：

  • Windows/macOS 可尝试host.docker.internal，Linux 环境需改用宿主机的局域网IP（如192.168.x.x），避免用127.0.0.1（容器内的127.0.0.1指向自身而非宿主机）。
  • 在容器内执行ping 宿主机地址，确认网络连通性。

• 检查端口与防火墙：

  • 确保宿主机防火墙允许9001端口的入站连接（Linux用ufw allow 9001，Windows/macOS在防火墙设置里放行）。
  • 确认VSCode的PHP Debug扩展确实监听9001端口，可在调试控制台查看是否有“Listening on port 9001”的提示。

• 分析Xdebug日志：

  • 查看容器内/tmp/x_debug.log的内容：
    • 若出现Could not connect to host，说明地址/端口不可达，回到前两步排查。
    • 若出现Connected to client但断点未触发，大概率是路径映射问题。

• 配置VSCode路径映射：

  • 在.vscode/launch.json中添加pathMappings，将容器内代码路径映射到宿主机本地路径，示例：

    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Listen for Xdebug",
                "type": "php",
                "request": "launch",
                "port": 9001,
                "ideKey": "VSC",
                "pathMappings": {
                    "/var/www/html": "${workspaceFolder}"
                }
            }
        ]
    }
    

  • 替换/var/www/html为容器内实际代码根目录，${workspaceFolder}为宿主机本地代码目录。

• 确认IDE Key一致性：

  • 确保php.ini中的xdebug.idekey与launch.json中的ideKey完全一致（注意大小写）。

• 验证Xdebug加载状态：

  • 在容器内执行php -m | grep xdebug，若输出xdebug则说明加载成功；若未输出，检查zend_extension的路径是否正确（PHP 5.6的Xdebug扩展路径通常为/usr/lib/php/20131226/xdebug.so，需根据实际安装路径调整）。

内容的提问来源于stack exchange，提问作者J.Cart