使用Docker与WSL2在VSCode中调试PHP遇问题求助

阿华AIGC实验室

2026-5-7

问题：WSL2环境下VSCode Remote调试PHP无反应

我在Windows系统使用VSCode+Docker已有多年，此前开发环境运行正常。近期搭建了基于WSL2的新开发环境，将所有项目、库、CLI等迁移至WSL，采用Windows Docker搭配WSL2容器，通过Windows端VSCode远程连接WSL工作，整体运行流畅。但最近遇到无法解决的问题：无法调试PHP文件。使用VSCode Remote WSL扩展在WSL内开发时，启动调试无任何反应，无错误输出、无调试控制台信息。我为Windows、MacOS、WSL三个环境分别配置了调试设置，仅WSL环境无效。

我的VSCode调试配置（.vscode/launch.json）如下：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug Win10",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true,
      "externalConsole": false,
      "pathMappings": {
        "/var/www/project-a/api": "\\\\wsl$\\Ubuntu\\home\\ubuntu\\PROJECTS\\project-a\\api"
      },
      "ignore": [
        "**/vendor/**/*.php"
      ]
    },
    {
      "name": "Listen for XDebug MacOS",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true,
      "externalConsole": false,
      "pathMappings": {
        "/var/www/project-a/api": "/Users/ricky/PROJECTS/project-a/api"
      },
      "ignore": [
        "**/vendor/**/*.php"
      ]
    },
    {
      "name": "Listen for XDebug WSL",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true,
      "externalConsole": false,
      "pathMappings": {
        "/var/www/project-a/api": "/home/ubuntu/PROJECTS/project-a/api"
      },
      "ignore": [
        "**/vendor/**/*.php"
      ]
    }
  ]
}

请问我哪里配置出错？有什么解决思路？

更新：

我找到了最优解决方案：@romain-prevost的方案可行，但@dark的方法更简单。

解决思路与配置修正

结合WSL2+Docker+VSCode Remote的特性，从以下几个关键点排查：

1. 修正XDebug的`client_host`（核心问题）

WSL2的网络和Windows宿主机是隔离的，XDebug运行在Docker容器中时，默认无法直接连接到Windows端的VSCode调试端口。你需要调整XDebug的配置：

XDebug 3.x：设置xdebug.client_host = host.docker.internal（Docker会自动解析到Windows宿主机IP），同时确认xdebug.client_port和VSCode配置的port一致（XDebug3默认是9003，你配置的是9000，所以要同步设置xdebug.client_port=9000）
XDebug 2.x：设置xdebug.remote_host = host.docker.internal，xdebug.remote_port=9000

如果host.docker.internal无法生效，也可以手动填入Windows宿主机的局域网IP（比如192.168.xx.xx），但前者是更通用的方式。

2. 验证路径映射的一致性

你的WSL调试配置中pathMappings的逻辑是对的（容器内路径 → WSL本地路径），但要确保：

Docker容器的代码挂载路径和配置中的/var/www/project-a/api完全一致
WSL本地的代码路径/home/ubuntu/PROJECTS/project-a/api确实是你VSCode打开的工作区路径
如果路径不匹配，XDebug无法关联到本地的PHP文件，也就不会触发断点。

3. 排查端口与防火墙问题

在WSL终端执行netstat -tulpn | grep 9000，确认9000端口没有被其他进程占用
检查Windows防火墙是否允许VSCode（或WSL进程）的9000端口入站连接
如果使用XDebug3，务必同步修改VSCode调试配置的port为9003（或保持和XDebug配置一致）

4. 查看XDebug日志定位问题

你已经开启了log: true，VSCode会生成XDebug调试日志。可以在VSCode的调试控制台找到日志路径，或者直接查看Docker容器内的XDebug日志（比如/var/log/xdebug.log，取决于你的容器配置）——日志会明确显示XDebug是否尝试建立连接、连接失败的具体原因（比如主机无法解析、端口不通等）。