一分钟内让 Xdebug 与 Docker 和 PHP 8.4 配合使用

2024 年 12 月 4 日

Xdebug 的设置学习曲线一直很陡峭。我在这里向您展示设置 Xdebug 并不是一件痛苦的事情。事实上，我相信您可以在大约一分钟内开始将 Xdebug 与 Docker 结合使用。

好的，也许这会占用你们一些人的几分钟时间:)

我们将使用 Laravel、PHP 8.4 和 Xdebug v3.4.0（撰写本文时的最新稳定版本）演示设置。

使用 Docker 镜像配置 Xdebug 所需的要点包括：

  • 安装 Xdebug 模块和配置的 Dockerfile
  • A compose.yaml 文件来启动容器
  • 可用作 Xdebug 客户端的受支持的编辑器或 IDE

项目设置

在这篇文章中，我们将使用 Apache 来简化服务器设置；但是，Dockerfile 代码与在 PHP-FPM 映像中配置 Xdebug 相同。

如果您想跟着我们一起来，我们将首先设置一个演示项目：

laravel new xdebug-demo --git --no-interaction
cd xdebug-demo
mkdir -p build/php/conf.d build/apache
touch compose.yaml \
build/Dockerfile \
build/php/conf.d/xdebug.ini \
    build/apache/vhost.conf

我们通过命令行为我们的设置创建了文件夹和文件，但您可以随意创建它们。除了典型的 Docker 文件外，我们还创建了一个 vhost.conf 文件来配置我们应用程序的 Web 根路径。

Docker 镜像设置

接下来，将以下内容添加到您的 build/Dockerfile 文件：

FROM php:8.4-apache as base

LABEL maintainer="Paul Redmond"

RUN docker-php-ext-install pdo_mysql opcache && \
    a2enmod rewrite negotiation

COPY build/apache/vhost.conf /etc/apache2/sites-available/000-default.conf

FROM base as development

RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini

COPY build/php/conf.d/xdebug.ini $PHP_INI_DIR/conf.d/xdebug.ini

RUN pecl channel-update pecl.php.net && \
    pecl install xdebug-3.4.0 && \
    docker-php-ext-enable xdebug

FROM base as app

RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini
COPY . /srv/app

Dockerfile 有相当多的行，因此让我们回顾一下最重要的代码，以帮助您了解如何配置 Xdebug。首先，我们使用多阶段构建，以便我们可以在开发环境中配置 Xdebug。在 development 阶段是 base 阶段，其中包含我们图像所需的基础设置，例如我们想要的 PHP 扩展 任何 环境并配置 Apache。

接下来 development 阶段复制开发版本的 PHP.ini 文件，复制 xdebug.ini 配置将保存我们对 Xdebug 所做的自定义。我们使用 v3.4.0 它支持 PHP 8.4，并且是撰写本文时的最新稳定版本。

最后，我们有一个 app 阶段，这是我们的应用程序映像将在生产版本中使用的。使用 app 目标省略了配置 Xdebug 并使用 php.ini 文件的生产版本。

阿帕奇虚拟主机

我们不是来学习如何配置 Apache 的，我们只是想用它来快速演示在 Docker 中设置 Xdebug 是多么容易。只需将以下代码添加到 build/apache/vhost.conf 文件，该文件被复制到 Docker 镜像中以指向应用程序代码：

<VirtualHost *:80>
 ServerAdmin webmaster@localhost
 DocumentRoot /srv/app/public

 <Directory "/srv/app/public">
 AllowOverride all
 Require all granted
 </Directory>

 ErrorLog ${APACHE_LOG_DIR}/error.log
 CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Xdebug 配置

接下来，我们需要通过 xdebug.ini 我们创建的文件。如果您按照以下步骤操作，请将以下内容添加到此文件中：

; build/php/conf.d/xdebug.ini file
[xdebug]
xdebug.mode = debug

xdebug.client_host = host.docker.internal

; Or use the host machine IP address:
; xdebug.client_host = 192.168.86.203

xdebug.start_with_request = yes

我们需要自定义来定义客户端主机。由于我们使用 Docker 网络，Xdebug 需要知道如何与我们的主机进行通信。如果您使用的是 Docker 桌面，Docker 有一个 host.docker.internal 指向您的主机的主机。

如果没有，您需要找到计算机的本地网络 IP 并使用它。我们可以使用环境变量来支持该值，但我将留到以后的帖子中再讨论。

最后，我们使用 xdebug.start_with_request = yes 始终在每次请求时启动 Xdebug。当我们不想使用 Xdebug 时，我们可以使用编辑器的 UI 禁用 Xdebug，但它始终会尝试建立连接。

运行镜像

在验证 Xdebug 连接之前，我们需要配置应用程序容器。我们将使用 Docker Compose 通过添加以下内容来使用 Docker 运行我们的应用程序 compose.yaml :

services:
  app:
    build:
      context: .
      dockerfile: build/Dockerfile
      target: development
    ports:
      - "8080:80"
    volumes:
      - .:/srv/app

我们的 app 服务目标 development 构建阶段，安装一个卷，以便我们可以在不重建映像的情况下更改代码，并使用端口 8080 在本地为应用程序提供服务。

我们现在可以使用 Docker Compose 构建并启动我们的镜像：

docker compose up --build -d

上面的命令将构建镜像、启动容器并在后台运行它。此时，Xdebug 已准备好接收连接，但是，我们需要在 IDE 中调整一件事才能使其正常工作。

配置 PhpStorm

我们将使用 PhpStorm，但您可以使用任何支持 Xdebug 的编辑器。由于我们使用 Docker，我们需要在 PhpStorm 中配置一个服务器，将我们的 Docker 卷映射到我们的本地项目代码。您可以通过打开 设置 > PHP > 服务器 并使用以下映射配置本地主机服务器 /srv/app :

如果你没有本地服务器，你可以使用端口从此设置页面添加一个 8080 并选择 Xdebug 调试器。服务器映射使我们的 IDE 能够了解如何将服务器堆栈跟踪映射到项目中的文件。

接下来，我们准备使用右上角菜单附近的 Bug 图标来启用 Xdebug，当您将鼠标悬停在它上面时会显示“开始监听 PHP 调试连接”：

当您单击它时，您应该会看到图标变成绿色。

我们要做的最后一件事是设置断点。打开 routes/web.php 文件并在主页路由的唯一行上设置断点：

如果您在 Web 浏览器中打开项目（ 本地主机：8080 )，PhpStorm 应该会提示您第一次连接。之后，它将在您设置的任何断点处自动暂停。完成调试后，您可以单击错误图标以禁用 Xdebug 连接。

了解更多

您现在应该能够在您的项目中使用 Xdebug 了！我还向您展示了一个附加主题 - 使用多阶段镜像来设置开发工具，并为生产设置设置单独的阶段。使用多阶段构建可以让您的镜像达到另一个灵活性水平。

如果你在设置 Xdebug 的编辑器部分遇到困难，PhpStorm 有大量关于如何 配置 Xdebug . Xdebug 的 文档 是另一个极好的参考，包括有关设置、工具、配置选项等的文档。

帖子 一分钟内让 Xdebug 与 Docker 和 PHP 8.4 配合使用 首先出现在 Laravel 新闻 。

加入 Laravel 时事通讯 获取最新信息 类似这样的 Laravel 文章将直接发送到您的收件箱。