远程Docker环境下VS Code配置Xdebug连接失败求助

问题背景 #

部署环境为运行Docker的远程服务器，通过VS Code远程SSH连接操作，Web请求通过反向代理发起。当前Xdebug配置如下：

xdebug.mode = debug
xdebug.client_host = "host.docker.internal" ; Linux
xdebug.remote_handler = dbgp
xdebug.start_with_request = yes
xdebug.client_port = ${XDEBUG_REMOTE_PORT}

已设置XDEBUG_REMOTE_PORT=9998，且确认Docker容器内host.docker.internal解析为72.24.0.1。远程主机执行nc -vz localhost 9998可正常连接（证明VS Code正在监听端口），但容器内执行nc -vz host.docker.internal 9998连接失败；本地机器的Docker容器执行相同命令却能正常连通。

VS Code的launch.json已配置绑定IPv4（hostname: "localhost"），docker-compose.yaml也添加了extra_hosts: - "host.docker.internal:host-gateway"配置。

可行解决方向 #

1. 调整VS Code监听的IP范围 #

当前launch.json中hostname设为localhost，意味着VS Code仅监听本地回环地址（127.0.0.1），而Docker容器通过host.docker.internal访问的是远程主机的Docker网关IP（72.24.0.1），不在监听范围内，导致连接失败。

修改launch.json的hostname为0.0.0.0，让VS Code监听所有可用IP：

{
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": 9998,
    "hostname": "0.0.0.0",
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}/www"
    },
    "xdebugSettings": {
        "max_data": -1,
        "max_depth": 1,
        "max_children": 100
    }
}

修改后重启VS Code的调试监听，再在容器内测试连接。

2. 检查远程主机防火墙规则 #

远程主机的防火墙（如ufw、firewalld）可能阻断了Docker网关IP段（72.24.0.0/16）访问9998端口：

• 若使用ufw，添加允许规则：

  sudo ufw allow from 72.24.0.0/16 to any port 9998
  

• 若使用firewalld，添加规则并重载：

  sudo firewall-cmd --add-rich-rule='rule family="ipv4" source address="72.24.0.0/16" port port="9998" protocol="tcp" accept' --permanent
  sudo firewall-cmd --reload
  

添加规则后重新测试容器内的连接。

3. 验证Docker网络路由 #

确认远程主机的Docker网络与主机网络间路由正常：

• 在远程主机执行ip route，查看是否存在指向Docker网桥（如docker0或自定义网桥）的72.24.0.0/16路由条目。
• 在容器内执行traceroute host.docker.internal，追踪数据包走向，定位阻断环节。

4. 替换host.docker.internal为具体IP #

若host.docker.internal解析的72.24.0.1是Docker网桥网关，可直接在Xdebug配置中写入该IP：

xdebug.client_host = "72.24.0.1"

同时确保VS Code监听该IP（或0.0.0.0），重启PHP服务后测试。

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