VSCode中配置PHP Xdebug调试需三步：安装启用Xdebug扩展、正确配置php.ini（Xdebug 3参数如xdebug.mode=debug）、设置VSCode launch.json（端口与pathMappings严格匹配）。
在 VSCode 中为 PHP 项目配置 Xdebug 调试器，核心是三步：安装并启用 Xdebug 扩展、配置 php.ini、设置 VSCode 的 launch.json。只要每步配对准确，调试就能顺利启动。
确认 PHP 环境已安装 Xdebug
先在终端运行 php -v 和 php --ini，确认当前 PHP 版本和配置文件路径。再执行 php -m | grep xdebug，若无输出说明未启用。推荐用官方安装方式：
- 访问 Xdebug Wizard，粘贴
php -i输出内容，它会给出适配你环境的安装指令 - 通常结果是下载
xdebug.so（Linux/macOS）或php_xdebug.dll（Windows），放进extension_dir目录 - 在
php.ini中添加一行：zend_extension=/path/to/xdebug.so（路径必须绝对且正确）
配置 php.ini 启用远程调试
Xdebug 3 与旧版语法不同，需使用新参数。在 php.ini（或单独的 xdebug.ini）中加入以下内容：
xdebug.mode = debug xdebug.start_with_request = trigger xdebug.client_host = 127.0.0.1 xdebug.client_port = 9003 xdebug.log = /tmp/xdebug.log ; 可选，出问题时查日志
注意：不要设 xdebug.remote_enable=1 这类 Xdebug 2 的写法，VSCode 会连不上。改完重启 Web 服务（如 Apache 或 PHP 内置服务器）。
立即学习“PHP免费学习笔记（深入）”；
在 VSCode 中安装插件并设置 launch.json
安装官方扩展 PHP Debug（由 Felix Becker 提供）。然后在项目根目录创建 .vscode/launch.json，内容如下：
大家都知道，在进行J2EE项目的开发过程中，在调试阶段如果只是修改了页面是不需要重启应用服务器的，比如不需要重启Tomcat。只需要在浏览器中 进行页面刷新即可。其实之所以不用重启Tomcat等应用服务器，其根本原因是因为我们可以在应用服务器的配置文件中设置虚拟目录，这样就可以知道web 项目所在的目录，于是就可以省去打包、然后再重新发布到服务器的步骤。感兴趣的朋友可以过来看看
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
关键点：
-
port必须和xdebug.client_port一致（默认 9003） -
pathMappings是重点：左边是服务器上 PHP 文件的绝对路径（如 Docker 容器内路径、WAMP 的C:\\wamp64\\www\\），右边是本地项目路径；两边必须严格对应，否则断点不命中 - 如果用 PHP 内置服务器（
php -S localhost:8000），确保xdebug.mode=debug已生效，且浏览器访问时加?XDEBUG_SESSION_START=1或装 Xdebug Helper 插件
开始调试与常见问题排查
设置好后，点击 VSCode 左侧调试图标 → 选择 “Listen for Xdebug” → 点绿色 ▶️ 启动监听。接着在代码行号左侧点击设断点，刷新网页即可停住。
如果没反应，快速检查：
- 运行
php -i | grep xdebug，确认xdebug.mode显示debug，且无警告提示扩展加载失败 - 打开
xdebug.log，看是否有 “Connection failed” 或 “Could not connect” - 检查防火墙是否拦截了 9003 端口（尤其 Windows 和 macOS）
- 确认没有其他程序（如另一个 VSCode 实例、PhpStorm）占用了 9003 端口
基本上就这些。配一次，后续项目复制 launch.json 并调下 pathMappings 就能复用。
