如何使用 vscode 对基于 Docker 的 PHP 进行断点调试

1. Visual Studio Code

1.1. 安装主程序

1.2. 安装扩展:PHP Debug

1.2.1. 安装

按快捷键 cmd + pctrl + p,然后输入 ext install php debug

注意:安装完成后必须重启 vscode。

1.2.2. 配置

打开一个 PHP 项目,点击菜单 Debug > Add Configuration,或按照下图操作:

详细配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9001, // 对应 XDebug 的配置
"stopOnEntry": true,
"pathMappings": {
// "容器中对应的项目地址": "本机项目地址"
// 绝对路径
"/var/www/html/test/": "${workspaceRoot}"
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9001
}
]
}

配置成功后,在项目下会生成一个包含该配置的目录,如下:

1
2
3
4
.
├── .vscode
│ ├── launch.json
├── 其它项目文件

2. Docker 下的 PHP 环境

提示:推荐直接克隆我之前封装的一个基于 Docker 的 LNMP 环境,当然你也可用使用你自己的 Docker PHP 环境,并根据具体环境对相关内容进行调整。

2.1. 安装、配置 XDebug 扩展

  • 修改 Dockerfile 文件,安装 XDebug

    1
    2
    3
    4
    5
    6
    7
    ...
    && mkdir -p /tmp/xdebug \
    && wget -c https://github.com/xdebug/xdebug/archive/2.6.0.tar.gz \
    && tar -xf 2.6.0.tar.gz -C /tmp/xdebug --strip-components=1 \
    && docker-php-ext-configure /tmp/xdebug --enable-xdebug \
    && docker-php-ext-install /tmp/xdebug \
    ...

    修改后,需要重新编译对应的镜像文件,更多安装扩展的方式请参考:Docker 中的 PHP 如何安装扩展

  • 配置 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 = 192.168.2.14

    说明:

    • remote_port 默认 9000,为避免冲突,建议改为 9001
    • remote_host 是宿主机的 ip 地址

2.2. 调整 Nginx server 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
server {

listen 80;
server_name my.test; # 这里替换你的域名
index index.html index.htm index.php;
root /usr/share/nginx/html/test;

...

location ~ .*\.(php|php5)?$ {
proxy_pass http://php_apache:8091; # 这里是对应的 apache 容器地址和端口
proxy_read_timeout 300;
proxy_send_timeout 300;
index index.php;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}

...
}

主要追加以下两个参数,用以解决在 debug 时 504 超时问题,具体数值可根据需要设置。

  • proxy_read_timeout
  • proxy_send_timeout

2.3. 暴露 XDebug 通信接口

修改 docker-compose.yml 文件,在 nginx 服务下通过 expose 暴露 9001 端口

使用如下命令重新启动服务

1
2
3
➜  docker-compose stop
➜ docker-compose down
➜ docker-compose up -d

3. 测试断点调试

按快捷键 F5 打开断点,此时在浏览器中访问网页,将跳转到 vscode 编辑器,并且样式如下:

说明:上图是一个 TP 项目,虽然没有手动设置断点,但是开启调试模式后,访问网页会首先进入根目录下的框架入口文件。