vscode使用xdebug调试php

关于xdebug调试php的相关知识，强烈建议很看一下我的这篇文章：可能是全网最详细的PhpStorm+xdebug远程调试php代码的教程，因为已经详细写过，所以本文就不会写太详细的东西。

xdebug调试原理

• 1、编辑器(在这里就是vscode)中有一个遵循DBGp协议的Xdebug插件，当点击监听按钮时，Xdebug插件就会在本地监听指定的端口(端口号可配置)，DBGp中的DBG其实就是debug中的三个字母，p就是protocol；
• 2、在浏览器上访问要调试的项目或文件，并在链接后添加“?XDEBUG_SESSION_START=xxxx”这样的一个参数；
• 3、由于有XDEBUG_SESSION_START参数，而xdebug是php的扩展，所以xdebug会接收到这个参数并开启debug功能，然后xdebug会通过DBGp协议向xdebug配置中指定的ip和端口(在php.ini中指定该ip该端口)发送一个请求，而Xdebug插件刚好在监听该端口，所以能接收到xdebug的请求，此时xdebug与Xdebug插件之间会建立连接(使用DBGp协议通讯)，并且Xdebug插件会把断点信息发送给xdebug；
• 4、xdebug收到了断点信息后，就知道运行到哪一行时需要停止并把debug数据返回给Xdebug插件，Xdebug插件接收到debug数据就会在编辑器中显示出来，于是我们就能看到debug数据；
• 5、当我们点击编辑器上的debug相关按钮(例如step over, step into, step out)时，Xdebug插件又会把这个指令发送给xdebug(通过DBGp协议)，xdebug接收到后，就知道应该要step over、step into还是step out等等，并且把执行结果返回给Xdebug插件，如此往复。

该步骤可参考xdebug官方文档，在Step Debugging中页内查找“Communication Set-up”往下移动一下即可看到。
详细的步骤，打开6.3 IDE to debugger engine communications，往上滚动即可看到IDE与DBG对话过程。

前提条件

安装xdebug扩展

想要用xdebug调试php代码，首先你电脑上的php需要安装xdebug扩展，至于怎么安装，则不在本文范围，安装后在phpinfo里会有xdebug

在php.ini中添加xdebug配置

要使用xdebug调用php，首先要给xdebug配置一些参数。以下是需要添加到php.ini中的配置，其中zend_extension这一行经常会写成zend_extension="xdebug.so"，具体可以参考这里

[xdebug]
zend_extension="/path/to/xdebug.so"

;xdebug3.0中用于代替之前的xdebug.remote_enable=On
xdebug.mode=debug

;xdebug3.0中用于代替之前的xdebug.remote_autostart，trigger对应之前的off，yes对应之前的on
xdebug.start_with_request=trigger

;xdebug3.0中用于代替之前的xdebug.remote_host
xdebug.client_host="127.0.0.1"

;xdebug3.0中用于代替之前的xdebug.remote_connect_back=On，它会自动从$_SERVER['HTTP_X_FORWARDED_FOR']
;或$_SERVER['REMOTE_ADDR']变量中获取ip，当然因为$_SERVER只有服务器模式有所以客户端模式是用不了的(可配置其它变量)
;如果找不到ip它会回退(fallback)到xdebug.client_host指定的ip
xdebug.discover_client_host=true

;xdebug3.0中用于代替之前的xdebug.remote_port
xdebug.client_port=9003

;固定填dbgp(因为目前只支持这个协议，也只有这个协议)
xdebug.remote_handler="dbgp"

;这是一个所有网上的文章都提到要设置但实际上却没啥用的参数(不信你可以注释掉试试，一切都正常)
xdebug.idekey="PHPSTORM"

添加配置后记得重启php-fpm，不同地方重启方法不同，比如windows集成环境可以直接在软件上点击重启按钮，macOS用brew安装的话，可以用brew services restart php-fpm来重启，Linux一般可以用systemctl restart php-fpm来重启。

安装php调试插件

先随意写一个(或打开一个)php文件，然后点击左侧的Run and Debug(快捷键shift+command+d)，然后再点击弹出来的窗口中的Run and Debug按钮（如果你的vscode里没有该按钮，请点击这里查看原因）

首次调试，如果你没有安装过调试插件，它会提示你还没有php调试扩展，我们点击Find PHP extension

点击后就会跳转到扩展里面，并自动搜索php的扩展分类，注意这个搜索关键字是自动输入的，由于第一个安装量最多，那我就们安装第一个吧

安装“PHP Debug”插件后再点Run and Debug还是没反应

创建launch.json调试配置文件

其实要调试php代码，是要添加配置文件的，上图中我们可以看到“create a launch.json file”，我们点击它就会自动创建一个launch.json文件

右击顶部的tab→Reveal in Side Bar，即可在左侧的侧边栏中看到刚刚创建的launch.json其实是在当前项目下的.vscode目录中的(点开头的文件在Mac/Linux系统中属于隐藏文件，所以你在访达里默认情况下是看不到这个文件夹的，除非你在访达里设置显示隐藏文件)

前面创建的launch.json有两个配置，这两个配置分别代表什么？我们需要修改里面的参数吗？

• Listen for Xdebug：翻译为“监听Xdebug”。意思是vscode监听一个你指定的端口(配置中的port参数)，启动调试后，xdebug会往该端口发送调试信息，这样vscode就可以把xdebug的调试信息展示出来，这个是用于网页的方式调试。
• Launch currently open script：翻译为“启动当前打开的脚本”。其实就是只调试当前脚本，以脚本的方式运行，vscode一样会监听一个端口(配置中的port参数)。

比如我现在有一个文件叫test2.php，我既可以在网页上通过这个链接来运行它

http://localhost/personal/get-short-video/test2.php

也可以直接在终端用命令来运行它

php ~/www/personal/get-short-video/test2.php

launch.json里的两个配置默认端口都是9000，网上很多教程会告诉你什么都不用改，那是因为他们用的是Windows，Windows并不开启php-fpm，而如果你用的是macOS或Linux，是会有php-fpm进程的，而php-fpm默认监听9000端口，如果你还是用9000端口，就会跟php-fpm的9000冲突(除非你用unix socket方式监听就不会冲突)，所以我们要修改一下端口，比如9001、9002等等(我是改成了9002)。

没有Run and Debug按钮

没有“Run and Debug”按钮，一定是你已经在工作空间中添加过配置文件了，只是你忘了或者没意识到而已。

如果下图，如果你往图中红框中拖入一个单独的php文件(注意一定是文件而不是文件夹)，然后点击左侧“有虫子的三角形按钮”→“Create a launch.json”

上图点击“Create a launch.json”后有三种情况：

• 1、你在拖入单独的php文件之前，左侧栏中没有添加过项目（是空的），那么它会直接在默认workspace空间中创建一个worksapce.json文件；
• 2、你在拖入单独的php文件之前，左侧栏中添加过一个项目，那么它会在该项目的文件夹下创建一个.vscode文件夹，并在里面创建一个launch.json文件；
• 3、你在拖入单独的php文件之前，左侧栏中添加过两个项目，那么它会弹出一个选择，需要你选择把workspace文件创建到哪个项目中。

---

这是上面说的第1种情况，它会在默认的文件夹中创建一个workspace.json文件

这个默认文件夹都是在当前用户文件夹下的，我这边是macOS，它的目录如下，它会在该目录下自动生成一个以随机数字(看起来是时间戳但发现又不太像)命名的文件夹，然后把workspace.json文件生成到该文件夹下

~/Library/Application Support/Code/Workspaces/

---

这是上面说的第2种情况，它会在该项目里面生成一个.vscode文件夹，再在该文件夹中生成一个launch.json文件

---

这是上边说的第3种情况，这种情况它会让你选择你是要把配置文件造成到哪里，前两个就是两个项目文件夹，最后一个是工作空间

这里又有两种情况：

• 1、如果你选择两个项目文件夹中的其中一个，那情况就会跟第2种情况一样，在那个文件夹中生成一个.vscode文件夹，再在该文件夹中生成一个launch.json文件；
• 2、如果你选择的是“workspace”，那么情况就会跟上边的第1种情况一下，它会自动在情况1中据说的那个默认的workspaces文件夹中创建一个workspace.json文件。

根据前面据说，只要你通过1、3两种情况创建了workspace.json，那么以后就算你添加的项目中没有创建launch.json，你也能调试，因为workspace.json中包括了launch.json的json，而且它是共享给各种项目用的(当然局限于调试单文件)，这就是为什么有时候你明明没有创建launch.json，但是它就是不显示“Run and Debug”按钮，也没有入口可以创建lauch.json文件的原因。

开始调试

脚本方式调试

脚本方式调试，不需要使用浏览器来访问php文件，你本地没有apache/nginx之类的也没问题，但一般只适合调试单个文件(多文件项目理论上应该也是可以的，不过我没试过)。

---

点击左侧图标进入Run and Debug窗口，然后给当前文件打个断点(在行号前面点一下，有个小红点就表示添置了断点)，然后第3步是选择“Launch currently open script”，最后点击第4步中的三角形运行程序就会开始进入调试

如果你用过phpstorm的脚本调试，就应该知道，它其实是用命令行的方式执行php脚本，并添加了一些xdebug选项

进入调试后，先别动，先去终端中运行lsof -i:9002查看一下当前9002端口

可以发现有三个进程，一个是php，另外两个是“Code\x20H”，\x20其实是ASCII码中的空格，而H其实是Helper的第一个字母，其实这个进程就是“Code Helper”，你在“活动监视器”里也可以查到该进程(还不止一个，当前这些进程不是都是我们因为我们调试代码而启动的，它本身就很多Helper)

这里补充一点，就是点这个下拉的小三角

它会弹出三个菜单，这三个菜单，其实是对应launch.json或workspace.json的launch部分中的三部分配置

如下图所示，这三部分配置，每部分的name值就是菜单名称

如果你想打开workspace.json看看，可以点击上图中的最后一个选项，“Add Config(worksapce)…”。

网页方式调试

网页方式调试，其实就是把前面“脚本方式调试”选择的“Launch currently open file”改为“Listen for Xdebug”，然后点击三角形运行

注意，要先把之前的debug监听给停止

否则会报9002端口已经被占用

但是你会发现还是没有任何反应！这是正常的，因为”Listen for Xdebug“是网页调试，现在你已经开启了，你应该去通过网页访问你要调试的文件(当然如果是有统一入口的项目，只需要访问项目入口即可，不需要指定该文件)，比如我这里的访问链接是

http://localhost/personal/get-short-video/test2.php

可是我访问之后，还是没有任何动静，这是怎么回事？—— 那是因为你没有告诉xdebug你要调试！

怎么告诉xdebug你要调试呢？两种方式：

• 1、url中添加一个“?XDEBUG_SESSION_START=xxxx”(具体见这里)，其中xxx是一个随意的字符串；
• 2、用浏览器插件，Chrome内核的浏览器可以用“Xdebug Helper”，Firefox用Xdebug-ext会好用点。

但无论用哪种方法，其实都是向cookie里添加一个XDEBUG_SESSION，并给它设置一个值而已，这个值可以是任意字符串。

---

URL添加XDEBUG_SESSION_START参数方式

注：cookie是通过http header里下发到浏览器的，你必须先step over让网页先跑一遍，才能看到这个cookie，如果你处于调试状态，由于http请求未返回，浏览器是收不到这个cookie的。

---

Chrome浏览器使用Xdebug Helper插件方式

注：这里的值是PHPSTROM是因为我平时用的是phpstorm，这个值是可以在Xdebug Helper插件的选项里设置的，事实上它可以是任意值。

---

以上两种方式，无论是哪种，只要刷新一下网页，它马上就会自动打开vscode并显示相关debug信息。为什么它会知道要打开vscode呢？因为xdebug会通过DBGp协议告诉9002端口(其实就是vscode的php debug插件监听的端口)，所以插件接收到这个请求就会自动打开vscode。

---

以上就是使用vscode调试php的教程，更详细的调试原理，还是看一下我的这篇文章吧：可能是全网最详细的PhpStorm+xdebug远程调试php代码的教程。