Windows11下VS Code监听Xdebug但无法建立连接求助

之前在Windows10上长期使用VS Code搭配PHP/Xdebug，运行一切正常。更换Windows11新电脑后，同步了VS Code所有设置与扩展，环境基于Docker容器部署，Xdebug检测工具显示安装正常，已关闭防火墙，执行netstat -aon可见8000端口处于监听状态，但使用Postman/Telnet访问localhost:8000时，调试器始终无法接受连接，怀疑是Windows11相关问题，以下是针对性排查与解决方案：

附当前launch.json配置：

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug on Docker",
            "type": "php",
            "request": "launch",
            "runtimeArgs": [
                "-S",
                "localhost:8000",
                "-t",
                "."
            ],
            "port": 9003,
            "pathMappings": {
                "/var/www/html/": "${workspaceFolder}"
            }
        }
    ]
}

排查与解决方案 #

• 修正launch.json的监听地址
  Docker容器内的localhost仅指向容器自身，无法映射到Windows11宿主机。将runtimeArgs中的localhost:8000修改为0.0.0.0:8000，让容器内的PHP内置服务器监听所有网卡，确保宿主机能正常访问。修改后片段：

  "runtimeArgs": [
      "-S",
      "0.0.0.0:8000",
      "-t",
      "."
  ]
  

• 检查Docker端口映射规则
  确认Docker容器的8000端口已正确映射到宿主机8000端口。在docker run命令或docker-compose.yml中，需包含-p 8000:8000（或对应端口）的映射配置，打通容器与宿主机的端口链路。

• 验证Xdebug远程连接配置
  在容器内的php.ini或xdebug.ini中，确保以下配置正确：

  xdebug.mode=debug
  xdebug.client_host=host.docker.internal
  xdebug.client_port=9003
  xdebug.start_with_request=yes
  

  host.docker.internal是Docker提供的特殊域名，可直接指向宿主机IP，规避Windows11的网络隔离限制。

• 关闭Hyper-V网络隔离影响
  部分Windows11环境下，Hyper-V的虚拟网卡隔离会阻碍容器与宿主机通信：

  1. 打开「控制面板」→「网络和共享中心」→「更改适配器设置」
  2. 找到Hyper-V虚拟网卡（通常命名为vEthernet (Default Switch)）
  3. 右键属性，取消勾选「Internet协议版本6 (TCP/IPv6)」，仅保留IPv4，随后重启Docker服务。

• 测试容器内连通性
  在容器内执行curl localhost:8000，确认PHP内置服务器正常响应；再执行curl host.docker.internal:9003，测试是否能连接到宿主机的Xdebug监听端口。

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