VSCode中PHP断点调试失败需依次验证Xdebug启用、配置php.ini参数（xdebug.mode=debug等）、安装PHP Debug插件、正确设置launch.json端口与pathMappings、并通过URL参数或xdebug_break()触发调试。
如果您在使用 VSCode 进行 PHP 开发时无法启动断点调试，可能是由于 Xdebug 扩展未正确安装、配置不匹配或 VSCode 的 launch.json 设置有误。以下是完成 Xdebug 集成并实现单步调试的具体操作路径：
本文运行环境：MacBook Air，macOS Sequoia。
一、验证 Xdebug 扩展是否已启用
此步骤用于确认 PHP 环境中 Xdebug 模块已加载且版本兼容当前 VSCode 的 PHP Debug 插件。若扩展未启用，后续所有调试配置均无效。
1、在终端中执行 php -v，检查输出中是否包含 with Xdebug 字样。
立即学习“PHP免费学习笔记（深入）”；
2、执行 php --ini 获取 php.ini 文件路径。
3、用文本编辑器打开该 php.ini，查找 zend_extension 行，确认其指向的 .so 文件存在且路径正确。
二、配置 php.ini 中的 Xdebug 参数
Xdebug 3 与旧版行为差异显著，必须使用新版参数名，否则 VSCode 将无法接收调试连接。重点确保启用远程调试并绑定到本地监听端口。
1、在 php.ini 中添加或修改以下内容：
xdebug.mode = debug
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003
xdebug.start_with_request = trigger
2、保存 php.ini 后，重启 Web 服务器（如 Apache 或 PHP 内置服务器）。
三、安装并配置 VSCode 的 PHP Debug 插件
VSCode 本身不内置 PHP 调试能力，需依赖由 xdebug.org 官方维护的 “PHP Debug” 扩展，该插件负责解析 Xdebug 协议并与 IDE 交互。
1、在 VSCode 扩展市场中搜索 PHP Debug，安装由 Felix Becker 发布的版本。
2、打开项目根目录，在命令面板中执行 PHP Debug: Install Xdebug Helper（如有提示）。
3、确认插件状态栏右下角显示 Xdebug is running 或类似提示。
四、创建并校准 .vscode/launch.json
launch.json 是 VSCode 调试会话的指令集，必须精确匹配 Xdebug 的通信协议版本、端口及路径映射规则，否则将出现 “connection refused” 或 “path not found” 错误。
1、在项目根目录下新建文件夹 .vscode（注意开头为英文句点）。
2、在该文件夹内创建 launch.json，内容如下：
{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html/": "${workspaceFolder}/" } } ] }
3、根据实际 Web 根目录调整 pathMappings 中的左侧路径，确保与 PHP 运行时访问的绝对路径一致。
五、触发并验证调试会话
调试启动依赖主动触发机制，Xdebug 不再默认监听所有请求，需显式激活，避免性能损耗和误中断。
1、在 PHP 代码中插入 xdebug_break(); 或在目标行左侧灰色区域点击设置断点。
2、在浏览器地址栏 URL 末尾添加 ?XDEBUG_SESSION_START=1 参数（如 http://localhost/index.php?XDEBUG_SESSION_START=1）。
3、在 VSCode 中点击绿色三角形按钮启动调试，确认左下角状态栏出现 Listening on port 9003。
