怎样在vscode中调试PHP应用与设置断点【教程】

VS Code 调试 php 依赖 xdebug 正确配置：需确认 php -v 含 xdebug ≥3.0、php.ini 启用 zend_extension 及 xdebug.mode=debug 等参数、安装 felixfbecker 的 PHP Debug 插件、配置 launch.json 的 pathMappings 与实际路径一致，并通过 ?XDEBUG_session=1 或 XDEBUG_MODE=debug 触发调试。

VS Code 本身不直接执行 PHP，调试依赖 xdebug 或 zend-debugger（主流是 xdebug），所以“能设断点”不等于“点一下就能停住”——关键在 PHP 运行时是否真的把调试信息发给了 VS Code。

确认 PHP 环境已加载 xdebug 并处于调试模式

很多断点不命中，根本原因不是 VS Code 配置错，而是 phpinfo() 里压根没看到 xdebug 模块，或它处于 off 状态。

• 运行 php -v，输出中必须包含 xdebug 字样且版本号 ≥ 3.0（推荐 3.3+）
• 运行 php --ini 找到 Loaded Configuration File 路径，打开该 php.ini
• 检查是否有类似以下配置（注意：xdebug 3 和 2 的配置项完全不同）：

zend_extension=xdebug xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=127.0.0.1 xdebug.client_port=9003

⚠️ 常见坑：xdebug.mode=off（默认值）、client_port 写成 9000（xdebug 3 默认是 9003，而 VS Code 默认监听 9003；若改了端口，VS Code 的 launch.json 也得同步改）

安装并启用 PHP Debug 插件（felixfbecker 插件）

VS Code 官方市场里搜 PHP Debug，认准作者是 felixfbecker（gitHub 仓库名 felixfbecker/vscode-php-debug），这是唯一被 xdebug 官方文档推荐的调试器。

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

• 安装后重启 VS Code（插件需激活）
• 确保没有同时启用其他 PHP 调试类插件（如旧版 PHP Tools 的调试功能），会端口冲突
• 插件启用后，状态栏右下角会出现 PHP Debug 字样（悬停可看 xdebug 版本）

配置 .vscode/launch.json 启动调试会话

项目根目录下建 .vscode/launch.json，内容不是通用模板，要匹配你的运行方式（CLI 还是 Web）。

• 如果是命令行脚本（如 php index.php）：

{   "version": "0.2.0",   "configurations": [     {       "name": "Listen for Xdebug",       "type": "php",       "request": "launch",       "port": 9003,       "pathMappings": {         "/var/www/html": "${workspaceFolder}"       }     }   ] }

• 如果是 Web 请求（浏览器访问 http://localhost/index.php）：

{   "version": "0.2.0",   "configurations": [     {       "name": "Listen for Xdebug",       "type": "php",       "request": "launch",       "port": 9003,       "pathMappings": {         "/var/www/html": "${workspaceFolder}"       },       "hostname": "localhost",       "url": "http://localhost/index.php"     }   ] }

重点看 pathMappings：左边是 PHP 进程里文件的绝对路径（echo __FILE__ 看到的），右边是本地项目路径。windows 用户注意用正斜杠或双反斜杠，例如 "C:/myproject"，不能写 "C:myproject"（JSON 解析失败）。

触发断点的两种可靠方式

设好断点后，VS Code 不会自动监听所有请求——你得明确告诉 xdebug：“这次请求我要调试”。

• Web 场景：在 URL 后加 ?XDEBUG_SESSION_START=1（xdebug 3 默认 session key 是 XDEBUG_SESSION，值任意非空，如 ?XDEBUG_SESSION=1）
• CLI 场景：命令前加环境变量，例如 XDEBUG_MODE=debug php index.php
• 更省事：浏览器装 Xdebug Helper 插件（chrome/firefox），点击图标开启调试，它会自动在请求头或 cookie 中注入调试标识

断点生效的前提是：xdebug 已连接上 VS Code（状态栏出现 “Xdebug listening” 提示），且请求路径和 pathMappings 完全对得上——哪怕多一个 / 都可能找不到文件。