VSCode配置Xdebug调试PHP需三步：启用Xdebug扩展（php -v验证）、安装PHP Debug插件并配置launch.json（端口9003需一致）、浏览器访问触发断点；配置正确后F5启动即可单步调试。
在VSCode中配置Xdebug调试PHP，核心是三步打通：PHP环境启用Xdebug扩展、VSCode安装并配置PHP Debug插件、浏览器触发断点。只要每步配置准确，调试就能顺利启动。
确认PHP已加载Xdebug扩展
打开终端运行 php -v，若输出中包含 xdebug 字样，说明扩展已启用；若没有，需手动安装并配置。Linux/macOS常用 pecl install xdebug，Windows建议下载对应PHP版本的 php_xdebug.dll，放入ext目录，并在 php.ini 中添加：
- zend_extension=php_xdebug.dll（Windows）或 zend_extension=xdebug.so（Linux/macOS）
- xdebug.mode=debug
- xdebug.client_host=127.0.0.1
- xdebug.client_port=9003（Xdebug 3+ 默认端口，非旧版9000）
- xdebug.start_with_request=yes（自动开启调试，省去手动加 ?XDEBUG_SESSION_START=1）
VSCode安装PHP Debug插件并设置launch.json
在VSCode扩展市场搜索安装 PHP Debug（作者：Felix Becker）。安装后，打开你的PHP项目根目录，按 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（macOS），输入 PHP: Select Interpreter，选择正确PHP路径（确保该PHP已启用Xdebug）。
接着生成调试配置：按 Ctrl+Shift+D 打开调试面板 → 点击齿轮图标 → 选择 PHP → VSCode会自动生成 .vscode/launch.json。确认其中关键项为：
立即学习“PHP免费学习笔记（深入）”；
- "name": "Listen for Xdebug"
- "type": "php"
- "request": "launch"
- "port": 9003（必须与php.ini中xdebug.client_port一致）
- "pathMappings": {"/var/www/html": "${workspaceFolder}"}（Docker或远程路径映射时需调整，本地开发通常可省略或设为"\/": "${workspaceFolder}"）
启动调试并验证断点生效
在PHP代码中点击行号左侧设断点（出现红点），按 F5 启动调试（选择 Listen for Xdebug 配置）。此时VSCode底部状态栏应显示 Listening on port 9003。
用浏览器访问目标PHP脚本（如 http://localhost/index.php）。如果Xdebug配置正确且网络通畅，VSCode会立即暂停在断点处，变量面板显示当前作用域变量，可单步执行、查看调用栈、监视表达式。
常见卡点提示：
- 断点不命中？检查 phpinfo() 页面中Xdebug是否启用、mode是否含debug、client_host/port是否匹配
- 提示“connection refused”？确认Xdebug未被防火墙拦截，且VSCode调试服务已在监听
- 路径映射错误导致无法定位文件？重点核对 pathMappings 中远程路径与本地路径的对应关系
基本上就这些。配置一次，后续所有PHP项目复用同一套逻辑，调试效率明显提升。
