需配置Xdebug扩展与VSCode调试器通信：一、确认PHP已安装兼容Xdebug；二、在php.ini中启用debug模式并设client_host/port/idekey；三、安装PHP Debug插件；四、创建launch.json映射路径并指定端口9003；五、VSCode监听后，URL加?XDEBUG_SESSION_START=VSCODE触发断点。
如果您是PHP开发者，希望在VSCode中实现对PHP代码的断点调试，则需要正确配置Xdebug扩展与VSCode调试器之间的通信。以下是完成该配置的具体步骤：
本文运行环境：MacBook Pro，macOS Sequoia。
一、确认PHP环境已安装Xdebug扩展
Xdebug必须作为PHP扩展被加载，且版本需与PHP主版本兼容。可通过phpinfo()或命令行验证是否启用。
1、在终端执行 php -v 查看PHP版本号。
立即学习“PHP免费学习笔记（深入）”；
2、执行 php -m | grep xdebug 检查Xdebug是否已加载。
3、若未显示xdebug，需通过pecl安装或手动编译启用，例如运行 pecl install xdebug 并在php.ini中添加 zend_extension=xdebug.so。
二、配置php.ini中的Xdebug参数
Xdebug 3.x起默认使用on-demand模式，需显式启用远程调试并指定IDE密钥和连接地址，确保与VSCode监听端口一致。
1、找到当前生效的php.ini路径，执行 php --ini 获取位置。
2、在php.ini末尾添加以下配置段：
[XDebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=VSCODE
三、在VSCode中安装并配置PHP Debug插件
VSCode本身不内置PHP调试能力，需依赖由Felix Becker维护的PHP Debug扩展，该插件基于Xdebug协议实现断点控制与变量查看。
1、打开VSCode扩展市场，搜索 PHP Debug 并点击安装。
2、安装完成后，按下 Cmd+Shift+P（macOS）调出命令面板。
3、输入 Preferences: Open Settings (JSON)，在settings.json中确认无冲突的php.debug设置。
四、创建VSCode调试配置launch.json
launch.json定义了调试会话的启动参数，包括监听端口、路径映射及触发方式，是Xdebug与VSCode建立连接的关键桥梁。
1、在项目根目录下进入 .vscode/launch.json 文件（若不存在则通过“运行”→“添加配置”生成）。
2、将配置内容替换为以下标准模板：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
五、启动调试并验证断点命中
完成前述配置后，VSCode需主动监听Xdebug连接请求，同时PHP脚本需携带触发标识，二者协同才能激活调试会话。
1、在VSCode左侧活动栏点击“运行和调试”图标，选择 Listen for Xdebug 配置并点击绿色开始按钮。
2、在PHP文件中任意可执行行左侧灰色区域单击，设置断点，会出现红色实心圆点。
3、在浏览器中访问目标脚本URL，并在查询参数中追加 ?XDEBUG_SESSION_START=VSCODE。
4、刷新页面后，VSCode应自动聚焦至断点行，变量窗口显示当前作用域全部变量值。
