使用 VSCode 和 Docker 调试 PHP

Posted 2023-02-22

【中文标题】使用 VSCode 和 Docker 调试 PHP

【英文标题】：Debug PHP with VSCode and Docker

【发布时间】：2019-03-05 20:30:28

【问题描述】：

我正在尝试使用 VSCode 调试在 Docker 上运行的 php 应用程序，但没有成功。

过去，我可以使用运行 WAMP Server 的 VSCode 轻松调试我的 PHP 应用程序，但自从我开始使用 Docker 后，我无法进行调试。在网上搜索了几个教程，在 *** 上查看了一些线程（例如：Docker and XDebug not reading breakpoints VSCode），但我仍然无法正常工作。

Dockerfile：

FROM php:7.1.8-apache

COPY /cms /srv/app/cms
COPY .docker/cms/vhosts/vhost.conf /etc/apache2/sites-available/cms.conf
COPY .docker/cms/vhosts/vhost-ssl.conf /etc/apache2/sites-available/cms-ssl.conf
COPY .docker/cms/vhosts/certificate.conf /etc/ssl/certs/certificate.conf
COPY .docker/cms/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

WORKDIR /srv/app/cms

RUN docker-php-ext-install mbstring pdo pdo_mysql
RUN pecl install xdebug 
RUN docker-php-ext-enable xdebug
RUN chown -R www-data:www-data /srv/app/cms
RUN openssl req -x509 -new -out /etc/ssl/certs/ssl-cert-cms.crt -config /etc/ssl/certs/certificate.conf
RUN a2ensite cms.conf
RUN a2ensite cms-ssl.conf
RUN a2enmod rewrite
RUN a2enmod ssl

xdebug.ini

[xdebug]
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000
xdebug.remote_connect_back=0
xdebug.remote_host='host.docker.internal'
xdebug.idekey='VSCODE'
xdebug.remote_autostart=1

docker-compose.yml

version: '3.7'
services:
cms:
  build:
    context: .
    dockerfile: .docker/cms/Dockerfile
  image: php:7.1.8-apache
  ports:
    - 18080:80
    - 14430:443
  volumes:
    - ./cms:/srv/app/cms
  links:
    - mysql
    - redis
  environment:
    DB_HOST: mysql
    VIRTUAL_HOST: my.app.localhost
    PHP_EXTENSION_XDEBUG: 1

VSCode：launch.json

"configurations": [
    
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "pathMappings": 
           "/srv/app/cms": "$workspaceRoot/my.app/cms",
        ,
        "port": 9000
    , 
        "name": "Launch currently open script",
        "type": "php",
        "request": "launch",
        "program": "$file",
        "cwd": "$fileDirname",
        "port": 9000
    
]

当我调试应用程序时，没有触发断点。我做错了什么？

更新： 根据一些建议，我更新了 docker-compose.yml 和 launch.json 文件，但没有任何改变。

docker-compose.yml

ports:
  - 18080:80
  - 14430:443
  - 9000:9000 //added new xdebug default port

launch.json

"configurations": [
    
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "pathMappings": 
           "/srv/app/cms": "$workspaceRoot/my.app/cms",
        ,
        "port": 9000,
        "log": true
    
]

VSCode 调试控制台：

<- launchResponse
Response 
seq: 0,
type: 'response',
request_seq: 2,
command: 'launch',
success: true 

更新 #2： 从 docker-compose.yml 设置中删除了 Xdebug 端口 (9000)。这是 xdebug 日志结果：

日志于 2018-09-30 22:21:09 打开 I: 连接到配置 地址/端口：host.docker.internal:9000。 E：超时连接到 客户端（等待：200 毫秒）。 :-( 日志于 2018-09-30 22:21:09 关闭

日志于 2018-09-30 22:21:17 打开 I: 连接到配置 地址/端口：host.docker.internal:9000。 E：超时连接到 客户端（等待：200 毫秒）。 :-( 日志于 2018-09-30 22:21:17 关闭

日志于 2018-09-30 22:21:18 打开 I: 连接到配置 地址/端口：host.docker.internal:9000。 E：超时连接到 客户端（等待：200 毫秒）。 :-( 日志于 2018-09-30 22:21:18 关闭

日志于 2018-09-30 22:21:18 打开 I: 连接到配置 地址/端口：host.docker.internal:9000。 E：超时连接到 客户端（等待：200 毫秒）。 :-( 日志于 2018-09-30 22:21:18 关闭

还有什么建议吗？

【问题讨论】：

1) 那么.. Xdebug 日志对此有何评论？展示下。 2) 你的主机操作系统是什么？

@LazyOne 我在调试控制台中得到的唯一输出是：

No -- Xdebug 自己的日志，不是 VSCode。见xdebug.org/docs/all_settings#remote_log

从日志中可以看到..它无法与VSCode建立连接。可能是：1）错误的主机（但host.docker.internal 应该没问题）。也许尝试平台特定名称； 2）您主机操作系统上的防火墙（确保VSCode可以监听任何接口等）； 3) VSCode 没有在监听（你没有指定你的主机操作系统......所以我不能建议具体的命令，但一般来说——netstat）。确保监听 TCP 9000 端口的是 VSCode； 4) Docker 网络（不允许连接离开 Docker 容器/网络）。

感谢 3 天以来一直在努力完成这项工作。

【参考方案1】：

您在docker-compose.yml 中缺少端口:9000（或:9001），

它需要是可连接的，IDE 才能从外部连接。

对于 VSCode，可能需要 PHP Debug 扩展来与 xdebug 交互。

默认的launch.json 只使用一次port: 9000 - 并且有log: true。

  "configurations": [
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": true
    , 
      "name": "Launch",
      "request": "launch",
      "type": "php",
      "program": "$file",
      "cwd": "$workspaceRoot",
      "externalConsole": false
    
  ]

另见vscode-php-debug 和starting the debugger。

【讨论】：

“它必须是可连接的，IDE 才能从外部连接。” 有趣的理论......检查 Xdebug 文档，它清楚地表明它是 Xdebug连接到调试客户端（在这种情况下为 VSCode）而不是其他方式？所以它不是传入连接（就像它用于 HTTP(s) 一样）而是 传出 并且不需要映射

@LazyOne 如果需要“侦听远程连接”（甚至可能“连接回来”），容器将需要公开端口。可能与xdebug.remote_connect_back=1... xdebug 需要在容器内运行。

它读取：the port to which xdebug tries to connect on the remote host.（在这种情况下是一个容器，类似于远程主机或虚拟机）。

您能澄清一下吗？它是 VSCode 监听 Xdebug 端口（本地，它正在运行的地方），而 Xdebug 不监听任何东西，它不接受任何连接，因为它只将它们发送出去。 xdebug.org/docs/remote#communication

Xdebug（在 Docker 容器/VM 中运行）尝试连接到 IDE（因此它是传出连接）。您不需要在 Docker 中公开该端口（因为它用于传入连接）。如果您在 Docker 中公开 xdebug 端口 .. 那么 IDE 将无法侦听传入连接 ... 因为端口将被 Docker 占用。容器内的防火墙或类似的东西（启用传出连接）——是的，如果你有这样的东西..但是暴露..让IDE连接到Xdebug——不。 P.S.我没有在这里接触任何 VSCode 配置，因为我自己没有使用它。

【参考方案2】：

通过以下设置设法解决了我的问题：

launch.json

    "version": "0.2.0",
    "configurations": [
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "log": true,
            "externalConsole": false,
            "pathMappings": 
                "/srv/app/cms": "$workspaceRoot/cms",
            ,
            "ignore": [
                "**/vendor/**/*.php"
            ]
        ,
    ]

xdebug.ini

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20160303/xdebug.so
xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_connect_back=0
xdebug.remote_host=host.docker.internal
xdebug.idekey=VSCODE
xdebug.remote_autostart=1
xdebug.remote_log=/usr/local/etc/php/xdebug.log

【讨论】：

所以最后你没有在 docker-compose.yml 中暴露端口 9000 ？

可以，不需要在docker中暴露9000端口。

我好几天都遇到同样的问题...我最终不从我自己的 docker-compose 文件中暴露了端口 9000，xDebug 开始工作了！谢谢一百万！

你把 xdebug.ini 文件放在哪里了？你只是把它添加到 php.ini 文件的末尾了吗？

@Jval90 我把xdebug.ini文件复制到我的docker的容器对应路径：/usr/local/etc/php/conf.d/xdebug.ini

【参考方案3】：

自 xdebug 版本 3 以来，配置名称发生了重大变化。

我目前的工作 dockerfile：

RUN apt-get update; \
        apt-get -y --no-install-recommends install \
            php7.4-dev \
            php-pear \
            libcurl3-openssl-dev \
            libmcrypt-dev \
            libxml2-dev \
            libpng-dev \
        ; \
        pecl install xdebug; \
         \
            echo "[xdebug]"; \
            echo "zend_extension=$(find /usr/lib/php/ -name xdebug.so)"; \
            echo "xdebug.mode=debug"; \
            echo "xdebug.start_with_request=yes"; \
            echo "xdebug.client_host=host.docker.internal"; \
            echo "xdebug.client_port=9001"; \
         >> /etc/php/7.4/mods-available/xdebug.ini; \
        phpenmod -v 7.4 xdebug; \

VSC 调试配置：

    "configurations": [
        
            "name": "XDebug (Docker)",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "pathMappings": 
                "/var/www/app": "$workspaceRoot",
            
        
    ]

更多信息：https://xdebug.org/docs/upgrade_guide

【参考方案4】：

Symfony 的 XDEBUG v3 示例

docker-compose.yml:

###> XDEBUG 3 ###
# Use your client IP here
# Linux: run "ip a | grep docker0"
# Windows (with WSL2): Run "grep nameserver /etc/resolv.conf  | cut -d ' ' -f2"
# MacOS: host.docker.internal
###< XDEBUG 3 ###
environment:
  XDEBUG_CLIENT_HOST: 172.17.0.1
  XDEBUG_CLIENT_PORT: 9003
  PHP_IDE_CONFIG: serverName=Docker
volumes:
  - ./xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini

xdebug.ini

xdebug.mode=debug,coverage
xdebug.start_with_request=yes
xdebug.client_host=$XDEBUG_CLIENT_HOST
xdebug.client_port=$XDEBUG_CLIENT_PORT

示例配置 vscode 修改路径映射

launch.json：

    "version": "0.2.0",
    "configurations": [
        "name": "Listen for XDebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "log": true,
        "externalConsole": false,
        "pathMappings": 
            "/appdata/www": "$workspaceRoot/api",
        ,
        "ignore": [
            "**/vendor/**/*.php"
        ]
    ,
]

【参考方案5】：

适用于在以下堆栈上运行的每个人：

Ubuntu XDebug 3 Laravel 帆

docker/8.0/php.ini

[xdebug]
xdebug.discover_client_host=true
xdebug.start_with_request=yes 

.env

SAIL_XDEBUG_MODE=develop,debug
# For linux only:
# you may read up about how to get the ip here: https://laravel.com/docs/8.x/sail#debugging-with-xdebug
SAIL_XDEBUG_CONFIG="client_host=172.22.0.1"

launch.json

"version": "0.2.0",
"configurations": [
    
        "name": "Listen for XDebug via Docker",
        "type": "php",
        "request": "launch",
        "port": 9000,
        "log": true,
        "externalConsole": false,
        "pathMappings": 
            "/var/www/html": "$workspaceRoot/www",
        ,
        "ignore": [
            "**/vendor/**/*.php"
        ]
    ,
] 

【参考方案6】：

好吧，我已经尝试了上述所有答案并且花了几个小时但没有成功，因为在上述所有答案中，一些概念对于像我这样的新 x-debug 用户来说并不清楚。我希望在使用 VS Code 的 PHP Debug 开始设置 x-debugger、在 docker 容器或远程服务器上运行之前，我能够了解以下概念。我相信这将有助于寻找此类问题的解决方案。

X 调试设置

我不确定我的机器是否应该被视为客户端主机或服务器主机，虽然这很明显，但是当您花费数小时进行配置时，简单的事情开始变得棘手。

xdebug.client_host

根据 X-debug Docs：

这个地址应该是the address of the machine where your IDE or debugging client is listening for传入调试连接。

我认为，上面这段文字不需要解释。因此，在我们的 x-debug 配置中进行如下设置，即 xdebug.ini：

xdebug.client_host=host.docker.internal

xdebug.remote_host

这对我来说有点棘手。实际上 x-debug 没有这样的配置，但我一直在想它。 :-)

PHP-调试设置

主机名

我一直在使用不同的配置，除了这个（因为在这个线程中没有人提到这个）:-) 并且没有成功。然后，我重新浏览了 PHP Debug 的文档，知道在我的情况下它必须设置为 localhost，然后试一试，然后砰！成功了！

"hostname": "localhost"

端口

应该与xdebug.client_port设置相同，默认值为9300。在上面的答案中反复提到。

路径映射

在尝试使用 VS Code PHP Debug 设置 docker 服务器时，这是另一个非常重要的配置。它是一个对象，必须将您的本地目录结构映射到服务器/容器目录，即 /home/user/proj/html: $workspaceRoot。我无法进一步解释它，它确实对我有用，我在这里提到过。如果有人解释，我会欢迎。

这是我的最终设置：

希望这将有助于并节省您的时间:-)