配置本地 docker 中运行的 PHP xdebug 环境

在最近的调试过程中一直无法正确断点，最后发现是 xdebug 的配置问题，记录一下。

在 Docker 中配置 PHP 和 Xdebug 调试环境，通常从以下几个步骤开始：

1. 创建一个包含 PHP 和 Xdebug 的 Dockerfile

首先创建一个 Dockerfile，包含 PHP 和 Xdebug 的安装步骤。以下是一个简单的示例：

1
2
3
4
5
6

FROM php:8.2-apache

RUN pecl install xdebug && docker-php-ext-enable xdebug

COPY ./php.ini /usr/local/etc/php/conf.d/
COPY ./000-default.conf /etc/apache2/sites-available/

此示例使用了官方 PHP 8.2 容器，并安装了 Xdebug 扩展。

2. 配置 php.ini 文件

在项目中创建一个 php.ini 文件，包含以下 Xdebug 配置：

1
2
3
4
5

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

• xdebug.mode=debug 启用调试模式。
• xdebug.start_with_request=yes 指示 Xdebug 对每个请求启动调试。
• xdebug.client_host=host.docker.internal 特殊 DNS 名称，用于从容器内访问主机。Docker 容器通常使用 host.docker.internal 这个别名来引用主机系统。对于 Docker Desktop for Mac 和 Windows 工作。
• xdebug.client_port=9003 是 Xdebug 3 中的默认监听端口。在 PhpStorm 中也使用相同端口。
• xdebug.idekey=PHPSTORM 设置 IDE key。这对应于您在 PhpStorm 中配置的 key。

3. 创建并配置虚拟主机（可选）

如果需要，创建一个 000-default.conf 文件，其中包含您的 Apache 虚拟主机配置：

1
2
3
4
5
6
7

<VirtualHost *:80>
    DocumentRoot /var/www/html/public
    <Directory /var/www/html/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

4. 构建并运行 Docker 容器

在 Dockerfile 所在的目录中运行以下命令：

1
2

docker build -t my-php-xdebug .
docker run -d -p 80:80 --name my-php-xdebug-instance -v $(pwd):/var/www/html my-php-xdebug-container

此命令将构建一个名为 my-php-xdebug 的 Docker 镜像，并使用名为 my-php-xdebug-instance 的实例运行它。将 80:80 映射到主机，以便通过 http://localhost 访问。

5. 配置 PhpStorm

配置 PhpStorm，并确保等待计算机接收 Xdebug 连接（点击小电话图标，启用 PHP debug 监听）。

对项目进行映射配置，确保在 PHPStrom 中可以断点到正确的位置。

6. 设置 PHP_IDE_CONFIG 环境变量

在运行容器时使用 --env 标志设置 PHP_IDE_CONFIG 环境变量：

1

docker run -d --env PHP_IDE_CONFIG="serverName=myServer" my-php-xdebug-instance

将 “myServer” 替换为在第 5 步的 PhpStorm 设置的服务器名称。这是比较重要的一步，如果不设置这个环境变量，那么在 PhpStorm 中断点将不会生效。