Mac 上 Docker 内的 Xdebug 无法工作

我将本地开发设置从 Linux 移植到新的 Mac 机器，但在让 Xdebug 在 Mac M1 Pro 机器中与 PhpStorm 配合使用时遇到问题。

我有一个包含 PHP 的容器，其中 Xdebug 安装并配置如下：

zend_extension=/usr/lib/php8/modules/xdebug.so
xdebug.mode=debug

xdebug.idekey=PHPSTORM
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.discover_client_host=1
xdebug.log=/var/log/xdebug.log

在 PhpStorm 中，我正在监听端口 9001（我将 9000 用于其他服务）。

以下是 docker 容器内的 Xdebug 日志：/var/log/xdebug.log

/var/www/html/app # tail -f /var/log/xdebug.log 
[49] [Step Debug] INFO: Checking header 'HTTP_X_FORWARDED_FOR'.
[49] [Step Debug] INFO: Checking header 'REMOTE_ADDR'.
[49] [Step Debug] INFO: Client host discovered through HTTP header, connecting to 172.18.0.4:9001.
[49] [Step Debug] WARN: Creating socket for '172.18.0.4:9001', poll success, but error: Operation in progress (29).
[49] [Step Debug] WARN: Could not connect to client host discovered through HTTP headers, connecting to configured address/port: localhost:9001. :-|
[49] [Step Debug] WARN: Creating socket for 'localhost:9001', poll success, but error: Operation in progress (29).
[49] [Step Debug] WARN: Creating socket for 'localhost:9001', connect: Address not available.
[49] [Step Debug] ERR: Could not connect to debugging client. Tried: 172.18.0.4:9001 (from REMOTE_ADDR HTTP header), localhost:9001 (fallback through xdebug.client_host/xdebug.client_port) :-(
[49] Log closed at 2022-03-15 16:28:46.957669

我不明白为什么连接没有发生/失败。

我还有一个docker-compose.yml具有上述服务 API 的文件

  api:
    build:
      context: .
    expose:
      - 8080
    container_name: api

我已经尝试过什么？

1. 更改 xdebug.ini 配置以使用远程主机docker.for.mac.localhost, then host.docker.internal但没有成功。
2. Changed start_with_request=trigger代替yes.
3. 禁用 Mac 防火墙，认为端口 9001 可能无法被 Docker 使用。

2022 年 8 月 19 日更新 - 这无法调试 cli 脚本（phpunit 测试）

下面提供的配置答案是通过 HTTP 请求工作的，但不适用于 phpunit 测试或 cli 脚本。

内容/etc/php8/conf.d/50_xdebug.ini

                                                                                 
zend_extension=/usr/lib/php8/modules/xdebug.so
xdebug.mode=debug

xdebug.idekey=PHPSTORM
xdebug.client_port=9001
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.log=/var/log/xdebug.log

调试不起作用，出现以下错误

Xdebug: [Step Debug] Could not connect to debugging client. Tried: 172.18.0.1:9001 (through xdebug.client_host/xdebug.client_port) :-(

当我的编辑器 PhpStorm 尝试运行这个时

[sshConfig://[email protected] /cdn-cgi/l/email-protection:2023]:/usr/bin/php -dxdebug.mode=debug -dxdebug.client_port=9001 -dxdebug.client_host=172.18.0.1 /var/www/html/app/vendor/phpunit/phpunit/phpunit --configuration /var/www/html/app/phpunit.xml --filter "/(Tests\\Unit\\App\\Services\\Maps\\GoogleMapsServiceTest::testGetPlaceFromId)( .*)?$/" --test-suffix GoogleMapsServiceTest.php /var/www/html/app/tests/unit/app/Services/Maps --teamcity

还有 docker 机器内的 /var/log/xdebug.log 日志

[326] [Step Debug] INFO: Connecting to configured address/port: 172.18.0.1:9001.
[326] [Step Debug] WARN: Creating socket for '172.18.0.1:9001', poll success, but error: Operation in progress (29).
[326] [Step Debug] ERR: Could not connect to debugging client. Tried: 172.18.0.1:9001 (through xdebug.client_host/xdebug.client_port) :-(
[326] Log closed at 2022-08-19 16:24:59.855397

我通过修改 phpunit 解释器配置以一种 hacky 的方式解决了这个问题。我不知道为什么/etc/php8/conf.d/50_xdebug.ini在这种情况下，设置为内部 docker 主机的值被忽略

xdebug.discover_client_host=1与 Docker 一起使用肯定不正确，您需要将其设置为 0。discover_client_host使用 HTTP 标头查看请求来自何处，但随着 NAT 参与 Docker，Xdebug（和 PHP）将看到它无法连接的 IP 地址或主机名。

Setting xdebug.client_host=host.docker.internalDocker 应该是正确的，这应该是网络网关地址，这也是你的主机的地址。

（即使xdebug.discover_client_host=1，因为 Xdebug 将回退到xdebug.client_host如果无法连接到通过 HTTP 标头发现发现的不正确的标头，请进行设置。）

如果您想查看更详细的日志，还可以添加xdebug.log_level=10，这应该能提供更多的见解。

您不需要“绑定端口”docker-compose.yaml对于 Xdebug，因为 Xdebug 确实建立了连接toIDE，因此不需要暴露端口来接收连接。