vscode+xdebug实现远程调试PHP项目代码

站长

2023年02月21日 21:52 · 阅读数 39

本文来由

由于近段时间难得空闲，打算研究学习优秀的框架源码。想着通过VS Code调试框架源码，观察框架执行流程，就想到了著名的XDebug。 XDebug本身支持远程调试，就先把框架源码丢一份到虚拟机，再面向搜索引擎解决配置问题。然后发现网上的文章大多说得不够准确，看得云里雾里的，跟着实操时发现很多坑。故留下本文作为记录，希望能帮到后来者。

需要搞明白的

网络文章很多没说明白的点， Xdebug远程调试基本原理，是通过定制的网络协议，对外访问特定的机器，询问里面的IDE有没有打点等调试请求，如有就把调试信息拿回来服务器执行调试，执行结果又会通知IDE，之后就等待IDE下一步调试，如此往复。所以Xdebug需要在远程代码所在机器的PHP配置中，设置IDE所在地址和端口， IDE所在机器不需要安装XDebug，但是要开放配置约定的端口。

准备工作

阅读下文前，请读者先安装好以下内容：

远程机器
- php 7.x/8.x
- php_xdebug拓展，版本号是3.x
- nginx
本地系统
- VS Code编辑器，已安装PHP Debug拓展
- chrome/firefox浏览器，在拓展商店搜索并安装官方插件「Xdebug helper」

上述工具的安装就不在这赘述了。

配置步骤详解

1. php_xdebug拓展

在php.ini末尾，添加以下必要内容：

xdebug.mode = debug,develop,trace
xdebug.start_with_request = yes
xdebug.client_host = 192.168.1.10
xdebug.client_port = 9003

以下解释每一条的作用：

xdebug.mode [官方文档]

XDebug3.x的新配置，用于指定可用的调试模式，支持英文逗号拼接多种模式。至少需要添加trace模式。而我的例子用了debug,develop,trace。

xdebug.start_with_request [官方文档]

XDebug3.x的新配置，控制是否激活函数追踪、步进调试等功能。用于替代xdebug.remote_autostart，可选值有yes、no，此处必须为yes。

xdebug.client_host [官方文档]

XDebug3.x的新配置，用于指定将调试数据包发送到哪个地址。此处有2种情况：

远程代码在同一内网的虚拟机时，这里设置为VS Code所在机器的内网IP地址。

远程代码在公网的VPS时，这里也2种情况：

本地有做DDNS域名解析的，设置为该DDNS域名。并在路由器添加好转发设置，转发到VS Code所在机器的内网IP地址。

本地使用内网穿透到公网服务器的，设置为该服务器的地址/域名。并在穿透工具的配置中，添加相关转发配置，转发到VS Code所在机器的内网IP地址。

本配置用于替代xdebug.remote_host。

xdebug.client_port [官方文档]

XDebug3.x的新配置，用于指定将调试数据包发送到哪个端口。可选值1-65535，VS Code所在机器没用被占用的端口都可以设置。不过一般设置为9003。用内网穿透工具的要配置好端口转发。用DDNS域名解析的，在路由器做好端口转发。另外提一句，由于有端口转发，此处设置的端口，和实际到达本地的端口可以不一样。本配置用于替代xdebug.remote_host。

2. PHP-FPM与NGINX

常规情况下，PHP请求时间一般设置在30-300秒。在调试时，这个时间远远不够，很容易导致调试过程中，服务器返回502、504的超时状态，妨碍调试。所以要修改远程机器的php-fpm、nginx的配置，延长超时触发时间。

2.1. NGINX

找到php-fpm配置文件nginx.conf，若发现文件中出现以下配置任意之一，统一改为7200或更多。没有出现的配置不用理会，也无需手动添加到配置文件中：

fastcgi_connect_timeout
fastcgi_send_timeout
fastcgi_read_timeout
proxy_connect_timeout
proxy_send_timeout

这些配置的单位均为秒。

2.2. PHP-FPM

找到php-fpm配置文件php-fpm.conf，一般是和php.ini放在一起。在php-fpm.conf里，找到配置

request_terminate_timeout

修改为7200或更多，该配置的单位为秒。

注意：不可超过上面2.1.中，在NGINX设置的超时时间，否则NGINX就优先触发504超时。

3. VS Code

vscode+xdebug实现远程调试PHP项目代码

如图所示，按顺序点击，即可创建调试配置文件。初始配置长这样：

vscode+xdebug实现远程调试PHP项目代码

把上图框起来的配置：

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003
}

改成这样：

{
  "name": "远程调试",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/www/wwwroot/thinkphp5/": "${workspaceFolder}/"
  },
  "hostname": "192.168.1.10"
}