如何使用 VSC 调试本地 docker 容器中运行的 PHP？

Question

背景
我的 PHP 网站有问题。为了解决这个问题，我想单步执行代码。我在一台使用 VSC 作为 IDE 的 Windows 计算机上。 PHP 在 docker 容器中与 nginx 容器并行运行。

问题
我不知道如何将我的 VSC 调试器与 docker 容器中的 PHP 运行时连接。
我安装/启用了 Xdebug 并添加了 launch.json，但 VSC 调试器对页面请求没有反应。

有关我尝试过的更多详细信息
Xdebug 似乎可以工作。至少

php -v

（在 php 容器中）返回

PHP 8.2.26 (cli) (built: Nov 21 2024 17:59:18) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.26, Copyright (c) Zend Technologies
with Xdebug v3.4.0, Copyright (c) 2002-2024, by Derick Rethans

我的 xdebug.ini 配置是：

zend_extension=xdebug
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host=host.docker.internal

我的launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Local docker Xdebug",
      "type": "php",
      "request": "launch",
      "hostname": "localhost",
      "port": 9003,
      "stopOnEntry": true,
      "pathMappings": {
        "/var/www/amc/plattform": "${workspaceFolder}\\amc"
      }
    }
  ]
}

然后我运行“Local docker Xdebug”，可以看到端口正在侦听。 当我发出请求时，页面会出现，但调试器不会连接/停止。

知道缺少什么吗？

更新
感谢下面的精彩评论，我添加了一个带有

xdebug_info();

的页面并启用了 xdebug 日志记录。

我得到：

[Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port).

所以我的容器无法连接到主机端口。这不是我第一次希望容器连接到主机端口。我什至在同一个 docker compose 文件的另一个容器中成功地完成了此操作。

受到这个答案的启发我添加了

 extra_hosts:
    - "host.docker.internal:host-gateway"

还是不太幸运。

我不认为这是正确的方法，但我也尝试将 9003:9003 添加到容器的已发布端口。我很惊讶错误消失了。不幸的是VSC还是没有反应。

信息页面显示

Debugger            Active  
Connected Client    host.docker.internal:9003

看起来很积极，但这独立于 VSC 调试器。因此，如果调试器没有监听，信息页面仍然告诉我“调试器：活动”（我猜是因为我的 docker 端口发布打开该端口以将其通过管道传输到容器中）。似乎 xdebug 只检查开放端口，而不检查真正的调试器是否在另一端侦听。

xdebug.log 显示

[7] Log opened at 2024-12-02 22:04:21.868029
[7] [Config] WARN: Not setting up control socket with default value due to unavailable 'tsc' clock
[7] [Step Debug] INFO: Connecting to configured address/port: host.docker.internal:9003.
[7] [Step Debug] INFO: Connected to debugging client: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port).
[7] [Step Debug] -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///var/www/amc/plattform/public_html/phpinfo-192837465.php" language="PHP" xdebug:language_version="8.2.26" protocol_version="1.0" appid="7"><engine version="3.4.0"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2024 by Derick Rethans]]></copyright></init>
[7] [Step Debug] -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" status="stopping" reason="ok"></response>
[7] Log closed at 2024-12-02 22:04:21.893973

还有什么想法可以尝试吗？

Answer 1

VSC 调试器端口正在侦听环回接口（尝试了 localhost 和 127.0.0.1）。

我分析了同一个 docker compose 中另一个容器->主机连接的差异，发现有效的连接监听 0.0.0.0:port（0.0.0.0 表示监听所有网络接口）。

简单地从我的 launch.json 中删除

"hostname"

参数后，xdebug 就能够连接了。

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Local docker Xdebug",
      "type": "php",
      "request": "launch",
      // "hostname": "localhost",   <= without this, the debugger listens on 0.0.0.0
      "port": 9003,
      "stopOnEntry": true,
      "pathMappings": {
        "/var/www/amc/plattform": "${workspaceFolder}/amc"
      }
    }
  ]
}