在 PHPStorm 中配置基于 Docker 的 xdebug

本文主要介绍在 PHPStorm 中如何配置 xdebug 进行断点调试,PHP 服务运行在 Docker 容器中。 此外,关于 vscode 的配置方式详见:如何使用 vscode 对基于 Docker 的 PHP 进行断点调试

1. Docker 设置

1.1. 在镜像中安装 xdebug

Dockerfile 文件中 xdebug 的安装方式如下:

1
2
3
4
5
6
7
8
9
10
11

...

# 【xdebug】
&& mkdir -p /tmp/xdebug \
&& tar -xf /tmp/xdebug.tar.gz -C /tmp/xdebug --strip-components=1 \
&& docker-php-ext-configure /tmp/xdebug --enable-xdebug \
&& docker-php-ext-install /tmp/xdebug \

...

这里主要使用 docker-php-ext-configuredocker-php-ext-install 来安装和启用 PHP 扩展,详见:Docker 中的 PHP 如何安装扩展

为了提高构建速度,这里用的是下载好的 xdebug 安装包,你也可以使用如下命令 wget -c https://github.com/xdebug/xdebug/archive/2.7.2.tar.gz 下载。

1.2. 配置 xdebug

php.ini 中加入以下配置

1
2
3
4
5
6
7
8
9
[XDebug]
;zend_extension = xdebug.so
xdebug.remote_enable = 1
xdebug.remote_handler = dbgp
xdebug.remote_port = 9001
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.idekey = docker
xdebug.remote_host = 10.254.254.254

注意:

  • xdebug.remote_port 指定的端口号需要从从容器中暴露出去;

  • xdebug.remote_host 用来配置宿主机的 IP 地址

    👍 最新:在 Docker v18.03+ 可以直接设置为 host.docker.internal,以自动解析宿主机的 IP。

    因为从 Docker 容器中无法通过 localhost127.0.0.1 访问宿主机,所有有以下三种解决办法:

    • 方式一:给宿主机设置一个固定 IP;
    • 方式二:每次启动服务前,检查宿主机的 IP 是否发生变化,并修改 php.ini 文件中 xdebug 设置,使其与宿主机保持一致。
    • 方式三:将地址设置为 10.254.254.254,并在宿主机执行命令 ifconfig lo0 alias 10.254.254.254 添加一个回环 IP(注意,这里的修改在宿主机系统重启后会失效)。

2. PHPStorm 设置

3. 测试

刷新项目,看到如下截图则配置成功。