xDebug 无法使用 docker、vscode 和 WSL 2答案

【问题标题】：xDebug not working using docker, vscode and WSL 2xDebug 无法使用 docker、vscode 和 WSL 2
【发布时间】：2025-11-25 07:20:07
【问题描述】：

我不确定问题是什么，它只是不起作用。

路由似乎有效，我的 nginx conf 文件中有一个服务器名称。例如测试网。行得通。

我的项目在 ubuntu 的根目录下，而不是在挂载文件夹中。

我不知道还能尝试什么。

xdebug.ini

[XDebug]
zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9002
xdebug.remote_handler=dbgp
xdebug.remote_connect_back=0
xdebug.remote_host=soapboxtest.com
xdebug.idekey=VSCODE
xdebug.remote_autostart=1
xdebug.remote_log=/usr/local/etc/php/xdebug.log

launch.json

{
  "name": "Listen for XDebug",
  "type": "php",
  "request": "launch",
  "port": 9002,
  "log": true,
  "externalConsole": false,
  "pathMappings": {
    "/var/www": "${workspaceRoot}"
  },
  "ignore": [
    "**/vendor/**/*.php"
    ]
  },

请求 cookie

"XDEBUG_SESSION" => "VSCODE"

Dockerfile

FROM php:fpm-alpine3.11
...
RUN pecl install xdebug
RUN docker-php-ext-enable xdebug
...

【问题讨论】：

标签： php docker docker-compose xdebug wsl-2

【解决方案1】：

这也发生在我身上，发现 XDEBUG 不是在寻找 Docker 守护进程主机。通过添加修复它：

"hostname": "0.0.0.0"

作为 VS Code 上 launch.json 的常规选项的一部分。

【讨论】：

太棒了，谢谢。有用。在此期间我找到了一个解决方法，您可以将远程主机设置为 linux 机器 ip 地址，问题是它不是静态的。

【解决方案2】：

在有一位同事帮助我配置 Xdebug 以从 VSCode 监听 WSL Remote 环境后，我查找了一个选项，当您单击 IDE 左下方的 WSL Remote 图标时会打开该选项：

远程 WSL：显示日志

它会打开一个 WSL 终端，它会显示（在几个信息之间）WSL 正在使用的 IP 地址。将此 WSL IP 添加到 xdebug.remote_host 值中，唯一能让 Xdebug 在 WSL2 环境（来自 WSL Remote VSCode 扩展）内的 Docker 容器中正常运行的方法是调整内部的应用程序路径launch.json 文件。

为此，在 launch.json 文件选项卡上单击鼠标右键，搜索并单击“复制路径”选项，然后将其粘贴到 pathMappings 设置中，就像这个示例一样（不要忘记调整路径删除相对于launch.json本身的信息，它是你的应用程序路径！）：

"pathMappings": {
      "/application": "paste here the path you've copied"
 }

试试吧，对我来说就像一个魅力。如果它也适合你，请投票给我的答案！

【讨论】：

【解决方案3】：

我已经花了很多天“扯我的头发”。我使用 docker。

在防火墙中添加规则以允许流量（取自/引用自：https://github.com/microsoft/WSL/issues/4171#issuecomment-559961027
如果这还不够清晰，请到那里获取屏幕截图）

在 Windows 开始菜单中，输入 Firewall 并选择 Advanced settings，然后选择 Inbound Rules

选择自定义规则。

点击下一步，直到您到达左侧菜单中的Protocol and Ports

选择 ICMPv4 作为协议类型。

选择下一步，直到您最终进入 Name 部分，输入任意名称并单击完成。

如果您现在尝试从 wsl2 ping 您的主机 IP，它应该可以作为预计。

对于您的 wsl2 和您的主机之间的所有其他连接，您有允许私有和公共网络的入站规则，或者如果它们不存在手动为对应的UDP/TCP创建规则端口，但请注意，如果您使用您的计算机在公共网络中。

.vscode/launch.json

{ “版本”：“0.2.0”， “配置”：[ { "name": "监听 XDebug", “类型”：“php”， “请求”：“启动”， “端口”：9900， “路径映射”：{ "/linux/path/in/docker":"${workspaceFolder}", } }, ] }

Dockerfile

RUN echo "zend_extension=/usr/lib/php/20190902/xdebug.so\n \
         xdebug.remote_enable=on\n \
         xdebug.remote_autostart=on \n \
         xdebug.remote_connect_back=on\n \
#         xdebug.remote_host=$HOST_IP\n \
#         xdebug.remote_log_level=9\n \
#         xdebug.remote_log=/var/www/mywebdir.com/xdebug.log \n \
         xdebug.remote_port=9900" > /etc/php/7.4/mods-available/xdebug.ini;

编辑：过了一会儿，我又开始遇到问题了。试试这些：

在 dockerfile 中取消注释上面的日志记录行
尝试对您的 Windows ip 地址进行硬编码，例如 192.168.0.x

（取消注释 xdebug.remote_host=... 并注释掉 xdebug.remote_autostart=on）

我的 xdebug 似乎已连接，但之后立即关闭连接，因为它必须是我的 windows ip。我的理解是它的 VSCode 响应在 windows 中运行的 xdebug 请求，因此调试数据包需要通过 WSL2。
尝试记录级别 10。如果您发现 xdebug 找不到断点的匹配项，请检查 docker 中的 webroot 映射和 vscode/launch.json 中的 pathMappings
检查您是否设置了断点（愚蠢但确实如此）

【讨论】：