用 Xdebug + VS Code 断点调试 PHP,告别 var_dump

「这段代码走到这了吗?」「这个变量现在到底是什么值?」

排查这类问题,很多人的第一反应是在代码里插入 var_dump($xxx); die;。一次两次还好,多了就变成噩梦:改完代码要刷新、看完要删、删漏了还会把调试信息带到线上。

断点调试能彻底改变这种体验:代码停在你想停的位置,变量值实时可看,还能一步步往下走。这篇文章手把手教你在 VS Code 里给 PHP 配上 Xdebug。

一、断点调试到底能干什么

在编辑器里点一下行号,这行代码就变成了「断点」。程序运行到这一行时停下来,你可以:

查看当前所有变量的值;
单步执行,一行一行看逻辑怎么走;
随时改查调用栈,知道是从哪调进来的;
不污染代码,调试完删掉断点就行。

对排查复杂 bug 来说,效率远超 var_dump。

二、Xdebug 是怎么工作的

Xdebug 是 PHP 的调试扩展。原理很简单:

PHP 进程加载 xdebug 扩展;
运行时按配置连接调试客户端(这里是 VS Code);
遇到断点就暂停,把变量、堆栈信息发给 VS Code。

它需要几项关键配置(Xdebug 3 的默认值):

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

其中 client_port 默认是 9003,VS Code 这边监听同一个端口就能接上头。

三、在 Xserver 里一键开启 Xdebug

手动编译 xdebug 是最劝退的环节:要匹配 PHP 版本、处理 phpize、头文件路径,错一步就白忙。Xserver 把这一步简化成了开关:

打开「PHP」菜单,选择你的 PHP 版本。
点击「扩展」入口,打开扩展列表。
找到 xdebug,把它「开启」。
回到 PHP 列表,点「重启」,让扩展生效。

重启后,可以点「phpinfo」确认 xdebug 已经加载,或者在终端执行:

picture.image

php -m | grep xdebug

能看到 xdebug,说明扩展就绪。Xserver 内置的 PHP 版本都预置了 xdebug 支持,不用自己编译。

四、VS Code 这边怎么配

先安装 PHP 调试插件:

打开 VS Code,进入扩展市场。
搜索「PHP Debug」(作者 xdebug),安装。

然后在项目根目录建一个调试配置。打开「运行和调试」面板,点「创建 launch.json」,选 PHP,得到类似这样的配置:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

关键就是 port: 9003,要和 php.ini 里的 xdebug.client_port 一致。

五、开始第一次断点调试

在 VS Code 里打开你的 PHP 文件,点行号打一个断点。
按 F5,启动「Listen for Xdebug」,底部状态栏出现监听中的提示。
在浏览器里访问对应站点,比如 http://my-blog.test。
代码执行到断点处自动停住,左侧面板能看到变量、调用栈,上方出现单步按钮(F10 单步跳过、F11 步入、Shift+F11 步出)。

picture.image

这就是调试的完整循环:打断点 → 访问页面 → 看变量 → 单步走 → 定位问题。

常见问题

1. 访问页面没进断点

按顺序排查:

VS Code 是否在监听(F5 启动,端口 9003);
php.ini 里 xdebug.mode=debug 是否设置,xdebug.start_with_request=yes 是否开启;
改完配置有没有重启 PHP;
Xdebug 2 和 3 的端口不同:老版本默认 9000,新版默认 9003,两边要一致。

2. 终端里跑脚本不进断点

Web 请求走 nginx + php-fpm,命令行脚本走 CLI SAPI,两者可能加载不同的 php.ini。确认 CLI 用的 PHP 版本和配置文件里也有 xdebug 配置。

3. xdebug 显示已开启,但 php -m 里没有

多半是改完配置没重启,或者重启的是另一个版本。去 Xserver 的 PHP 列表确认目标版本的扩展开关和重启操作都执行了。

4. 端口被占用

9003 被其他程序占用时,换一个端口,同时改 php.ini 的 xdebug.client_port 和 launch.json 的 port,保持一致。

最后

断点调试上手后,你会发现自己再也不想回到 var_dump 时代。配合 Xserver 里的一键扩展管理,整个配置过程不超过 5 分钟。

遇到问题欢迎在评论区留言,也可以到 Xserver 官网反馈 bug 和建议。下载地址:https://x-server.ltd。