VSCode for PHP：Xdebug调试配置终极图文指南

VSCode调试PHP核心是Xdebug与VSCode成功通信：确保端口（9003）通畅、路径映射准确、xdebug.mode=debug且xdebug.start_with_request=yes启用；配置PHP Debug插件及launch.json的pathMappings；启动监听后浏览器访问即可触发断点。

VSCode 调试 PHP 项目，核心不是装插件，而是让 Xdebug 和 VSCode 真正“对上话”——端口通、路径映射准、触发方式对。只要这三关过了，断点一打就停，变量一查就出，调试就从玄学变日常。

确认 Xdebug 已正确安装并启用

先别急着开 VSCode，确保 PHP 环境里 Xdebug 是活的。在终端运行：
php -v，看到类似 with Xdebug v3.3.1 就说明已加载；再运行 php --ini 查看配置文件位置，打开它（通常是 php.ini 或 xdebug.ini），确认含以下关键配置（Xdebug 3+ 写法）：

• zend_extension=xdebug（路径可省略，VSCode 插件会自动找）
• xdebug.mode=debug（必须开启 debug 模式）
• xdebug.start_with_request=yes（每次请求自动启动调试，省得手动加 ?XDEBUG_SESSION_START=1）
• xdebug.client_host=127.0.0.1（本地开发填 127.0.0.1；Docker 或 WSL 用户按实际宿主机 IP 改）
• xdebug.client_port=9003（Xdebug 3 默认端口，VSCode 默认也监听 9003，保持一致）

改完重启 Web 服务（如 Apache/Nginx）或 PHP-FPM。用 php -m | grep xdebug 快速验证模块是否启用成功。

安装并配置 VSCode 的 PHP Debug 插件

在 VSCode 扩展市场搜 PHP Debug（作者：Felix Becker），安装并重载窗口。这是官方推荐、Xdebug 官网认证的调试器，别选错成旧版 “PHP Debug” 或其他名字相近的。

立即学习“PHP免费学习笔记（深入）”；

接着配置 .vscode/launch.json（菜单栏 → 运行 → 打开启动配置 → 选择 PHP）：

• 如果自动生成了配置，检查 "port" 是否为 9003；
• 重点设好 "pathMappings"：把服务器上的绝对路径（如 /var/www/html/）映射到你本地项目文件夹（如 /Users/you/project/）。这是断点能命中、变量能读取的关键——路径对不上，VSCode 根本不知道该停在哪一行；
• 常见写法：
  "pathMappings": { "/var/www/html/": "${workspaceFolder}/" }

Windows 用户注意斜杠方向，统一用正斜杠 / 或双反斜杠 \，别混用。

零一万物开放平台

零一万物大模型开放平台

48

查看详情

启动调试并验证断点是否生效

配置完别急着跑，分三步走：

• 在 VSCode 里打开一个 PHP 文件，在某行左侧灰色区域单击设断点（红点出现）；
• 点击 VSCode 左侧活动栏的「运行和调试」图标（Ctrl+Shift+D），选择「Listen for Xdebug」启动监听（小绿虫图标亮起）；
• 在浏览器中访问你的 PHP 页面（如 http://localhost/index.php）；

如果一切正常，VSCode 会自动跳转到断点行，顶部出现调试工具栏，变量面板显示当前作用域所有变量。鼠标悬停变量也能实时看值。若没反应，优先检查：
① Xdebug 日志（加 xdebug.log=/tmp/xdebug.log 到 php.ini）看连接是否被拒绝；
② 防火墙或杀毒软件是否拦了 9003 端口；
③ Docker 容器是否做了端口映射（-p 9003:9003）且 client_host 指向宿主机。

进阶技巧：CLI 脚本调试与条件断点

不只是 Web 请求能调试。想调试命令行脚本（比如 php artisan migrate）？只需在终端执行前加环境变量：

• XDEBUG_MODE=debug php your-script.php
• VSCode 保持「Listen for Xdebug」运行状态即可捕获。

条件断点也很实用：右键断点 → 「编辑断点」→ 输入表达式，比如 $i > 100，只在满足条件时暂停，避免循环里反复打断。

基本上就这些。不复杂但容易忽略细节——端口、路径、模式开关，三者齐备，Xdebug 就是 PHP 开发最顺手的显微镜。

以上就是VSCode for PHP：Xdebug调试配置终极图文指南的详细内容，更多请关注php中文网其它相关文章！