VirtualBox内Docker容器Xdebug无法连接宿主机VSCode PHPDebug问题

显性配置错误优先修复 #

首先修正xdebug.ini里的低级拼写错误：你写的xdebug.remove_connect_back=0参数名错误，正确参数为xdebug.remote_connect_back，把remove改成remote，否则该配置完全不生效。
另外你配置的xdebug.remote_host值错误：Xdebug是容器内主动向外发起连接到IDE的客户端，不需要填Vagrant私网IP，要填容器视角下能访问到Vagrant虚拟机的网关地址，Docker默认网桥环境下该地址通常是172.17.0.1。
修正后的Xdebug 2.x版本完整配置（你当前用的参数体系对应Xdebug 2.x）：

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_connect_back=0
xdebug.remote_host=172.17.0.1
xdebug.remote_port=9001
xdebug.remote_log=/tmp/xdebug.log

端口转发逻辑修正 #

你同时配置Vagrant端口转发、Docker 9001端口映射是完全搞反了连接方向：

• Xdebug是主动向外连接IDE监听的端口，不是对外提供服务，Docker compose里不需要配置9001:9001的端口映射，该配置会占用Vagrant虚拟机的9001端口，直接导致转发冲突，删掉这部分映射配置。
• Vagrantfile里的端口转发要明确绑定回环地址，避免防火墙拦截，配置如下：

config.vm.network "forwarded_port", guest: 9001, host: 9001, host_ip: "127.0.0.1", auto_correct: true

配置修改后执行vagrant reload重载虚拟机生效。

VSCode配置补全 #

你当前的launch.json缺少外层结构，且未明确监听地址，补全后的完整配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/core": "e:/core"
            },
            "port": 9001,
            "log": true,
            "hostname": "127.0.0.1"
        }
    ]
}

注意确认/core是容器内代码的真实绝对路径，和你实际挂载路径完全一致，否则会出现断点不命中的问题。

连通性验证步骤 #

所有配置修改完成后，重启PHP-FPM服务/对应Docker容器，按顺序验证：

1. 先启动VSCode的Xdebug监听，在Windows命令行执行netstat -ano | findstr 9001，确认127.0.0.1:9001处于监听状态。
2. 进入Vagrant虚拟机，执行nc -zv 127.0.0.1 9001，返回succeeded说明Vagrant到宿主机的端口转发正常。
3. 进入运行PHP的Docker容器，执行nc -zv 172.17.0.1 9001，返回succeeded说明容器到Vagrant虚拟机的连接正常。
4. 触发任意PHP请求，查看容器内/tmp/xdebug.log即可看到连接记录，若仍有断点不命中问题，对照日志调整路径映射即可。

补充说明：如果你实际用的是Xdebug 3.x版本，所有配置参数前缀需要从xdebug.remote_*改为xdebug.client_*，对应参数为xdebug.client_host=172.17.0.1、xdebug.client_port=9001，同时开启xdebug.start_with_request=yes即可。

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