用 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 已经加载,或者在终端执行:
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 步出)。
这就是调试的完整循环:打断点 → 访问页面 → 看变量 → 单步走 → 定位问题。
常见问题
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。
