首先安装配置XDebug扩展并修改php.ini，然后在VSCode中安装PHP Debug插件，接着配置launch.json设置端口和路径映射，最后通过设置断点启动调试，确保XDebug加载正常、端口一致即可实现本地PHP调试。
在使用 VSCode 进行 PHP 开发时，配置 XDebug 能极大提升调试效率。通过断点、变量查看和单步执行等功能，可以快速定位问题。下面介绍如何在 VSCode 中正确配置 XDebug，实现本地 PHP 调试。
安装并配置 XDebug 扩展
XDebug 是一个 PHP 扩展，必须先安装到你的 PHP 环境中。
1. 下载合适版本的 XDebug：访问 https://www.php.cn/link/c1f0986fd7eefc02708427c7b8fada90，根据你的 PHP 版本和系统选择对应扩展。2. 修改 php.ini 文件，添加以下配置（路径根据实际调整）：
[XDebug]
zend_extension="path/to/php_xdebug.dll" ; Windows
; zend_extension=/usr/lib/php/extensions/... ; Linux/Mac
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log="/path/to/xdebug.log" ; 可选：用于排查连接问题
VSCode 安装 PHP Debug 插件
VSCode 需要借助插件与 XDebug 通信。
1. 打开 VSCode，进入扩展市场（Ctrl+Shift+X）。2. 搜索 “PHP Debug”，安装由 Felix Becker 提供的 php-debug 插件。
3. 安装完成后无需额外设置，插件会监听默认端口 9003。
配置 launch.json 启动调试
让 VSCode 知道如何启动调试会话。
立即学习“PHP免费学习笔记（深入）”；
1. 在项目根目录打开命令面板（Ctrl+Shift+P），输入 “Debug: Add Configuration”。2. 选择 “PHP” 并创建 launch.json 文件，内容如下：
{ "version": "0.2.0", "configurations": [ { "name": "Listen for XDebug", "type": "php", "request": "launch", "port": 9003, "pathMappings": { "/var/www/html": "${workspaceFolder}" } }, { "name": "Launch Built-in Web Server", "type": "php", "request": "launch", "runtimeExecutable": "php", "runtimeArgs": [ "-S", "localhost:8000" ], "program": "", "cwd": "${workspaceFolder}", "port": 9003, "serverReadyAction": { "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started", "uriFormat": "http://localhost:%s", "action": "openExternally" } } ] }
注意：- 如果你使用 Docker 或远程服务器，需调整 pathMappings 路径映射。
- port 必须与 php.ini 中 xdebug.client_port 一致（新版 XDebug 默认 9003）。
开始调试 PHP 脚本
配置完成后即可开始调试。
1. 在 PHP 文件中设置断点（点击行号左侧）。2. 启动调试：点击运行视图中的 “Listen for XDebug” 并按 F5。如果你用内置服务器，选择第二个配置。
3. 访问页面（如 http://localhost:8000/test.php），程序会在断点处暂停。
4. 查看变量、调用栈，使用工具栏进行单步跳过、进入等操作。
基本上就这些。只要 XDebug 正确加载，VSCode 插件正常运行，并且端口匹配，调试就能顺利工作。遇到连接失败时，检查 phpinfo() 是否显示 XDebug，查看日志文件是否有错误提示。整个过程不复杂但容易忽略细节。
