必须正确配置Xdebug扩展与VSCode的PHP Debug插件才能实现PHP断点调试：先确认PHP与Xdebug版本兼容，再配置php.ini启用Xdebug 3，接着安装并配置VSCode插件，然后创建launch.json启动配置，最后通过URL参数触发调试会话。
如果您在使用 VSCode 进行 PHP 开发时希望实现断点调试、变量查看与单步执行，则必须正确配置 Xdebug 扩展与 VSCode 的 PHP Debug 插件。以下是完成该配置并启动调试的具体步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、确认 PHP 与 Xdebug 版本兼容性
Xdebug 的功能和配置项随版本变化显著，3.x 与 2.x 在启用方式、配置参数及通信协议上存在根本差异，混用将导致调试连接失败。需确保所安装的 Xdebug 版本与当前 PHP 版本二进制兼容，并匹配 VSCode 中 PHP Debug 插件支持的协议版本。
1、在终端中执行 php -v 查看 PHP 主版本号（如 8.2）。
立即学习“PHP免费学习笔记（深入）”；
2、执行 php -m | grep xdebug 检查 Xdebug 是否已加载；若无输出，说明未启用或未安装。
3、执行 php --ri xdebug 获取 Xdebug 版本及详细编译信息，重点关注 Version 和 Supports phpinfo() 字段。
二、配置 php.ini 启用 Xdebug 3
Xdebug 3 默认禁用远程调试，必须显式启用并指定 IDE 密钥、客户端主机及端口，才能响应 VSCode 发起的调试请求。配置错误将导致“无法连接到 Xdebug”或“超时”提示。
1、执行 php --ini 找到正在使用的 php.ini 文件路径。
2、用文本编辑器打开该文件，在末尾添加以下区块（请勿复制旧版 Xdebug 2 配置）：
3、[xdebug]
4、zend_extension=xdebug
5、xdebug.mode=debug
6、xdebug.start_with_request=trigger
7、xdebug.client_host=127.0.0.1
8、xdebug.client_port=9003
9、xdebug.idekey=VSCODE
三、安装并配置 VSCode PHP Debug 插件
VSCode 本身不内置 PHP 调试能力，需依赖由 xdebug.org 官方维护的 PHP Debug 扩展（作者 felixfbecker），该插件实现了 DBGp 协议客户端，负责监听指定端口并解析 Xdebug 发送的调试数据包。
1、在 VSCode 扩展市场中搜索 PHP Debug，点击安装。
2、安装完成后重启 VSCode。
3、按下 Cmd+Shift+P（macOS）调出命令面板，输入 Preferences: Open Settings (JSON) 并回车。
4、在 settings.json 中添加如下配置项（若已存在则修改）：
5、"php.debug.executablePath": "/usr/local/bin/php"
6、"php.debug.port": 9003
7、"php.debug.log": true
四、创建 launch.json 启动配置
launch.json 定义了 VSCode 如何启动或附加到 PHP 进程，是触发调试会话的核心配置文件。缺少此文件或配置类型错误（如误选 "launch" 而非 "attach"）将导致调试按钮不可用或连接被拒绝。
1、在项目根目录下新建 .vscode/launch.json（若目录不存在请先创建）。
2、填入标准 Web 服务器调试配置：
3、{
4、"version": "0.2.0",
5、"configurations": [
6、{
7、"name": "Listen for Xdebug",
8、"type": "php",
9、"request": "launch",
10、"port": 9003,
11、"pathMappings": {
12、"/var/www/html/": "${workspaceFolder}/"
13、}
14、}
15、]
16、}
五、启动调试并验证连接状态
调试会话能否建立取决于三个同步条件：Xdebug 已就绪并监听客户端、VSCode 已启动监听、HTTP 请求携带有效触发参数。任一环节缺失都将表现为“等待连接”或“Connection refused”。
1、在 VSCode 左侧活动栏点击 运行和调试 图标（Ctrl+Shift+D）。
2、点击顶部绿色三角形按钮或按 F5 启动监听。
3、在浏览器地址栏当前 URL 末尾手动追加 ?XDEBUG_SESSION_START=VSCODE（注意大小写与拼写）。
4、刷新页面，VSCode 应立即在左侧变量面板显示 $_GET、$_SERVER 等上下文，且代码行左侧可设断点并高亮暂停。
5、若未触发，检查 VSCode 右下角状态栏是否显示 Xdebug listening on 127.0.0.1:9003；若未显示，说明插件监听未启动。
