VSCode配置Xdebug调试需三步：PHP启用Xdebug扩展（xdebug.mode=debug等）、VSCode安装PHP Debug插件并配置launch.json（端口9003、pathMappings映射路径）、通过浏览器插件/XDEBUG_MODE=debug/cli调用触发断点。
在 VSCode 中配置 Xdebug 进行 PHP 调试，核心是三者协同：PHP 环境启用 Xdebug 扩展、VSCode 安装并配置 PHP Debug 插件、浏览器或 CLI 触发调试会话。只要路径和端口对得上，调试就能连通。
确认 PHP 已加载 Xdebug 扩展
打开终端，运行 php -v 或 php --ini，检查输出中是否含 xdebug 字样。若没有，需先安装并启用：
- Linux/macOS 常用 pecl install xdebug，Windows 用户建议用 XAMPP/MAMP 集成环境自带的扩展开关
- 编辑 php.ini，添加或确认以下配置（Xdebug 3+ 版本）：
[xdebug] zend_extension=xdebug.so ; Linux/macOS ; zend_extension=php_xdebug.dll ; Windows xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.log=/tmp/xdebug.log ; 可选，排错时开启
改完重启 Web 服务（如 Apache/Nginx）或 PHP-FPM。再运行 php -m | grep xdebug 验证是否加载成功。
安装并配置 VSCode 的 PHP Debug 插件
在 VSCode 扩展市场搜索 PHP Debug（作者 Felix Becker），安装后无需手动配置 launch.json 即可启动基础调试。但推荐显式配置以提升稳定性：
立即学习“PHP免费学习笔记（深入）”；
- 按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Preferences: Open Settings (JSON)，确保 php.debug.executablePath 指向你的 php 可执行文件（如
/usr/bin/php或C:\xampp\php\php.exe） - 在项目根目录创建 .vscode/launch.json，内容如下（适配 Xdebug 3）：
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/": "${workspaceFolder}/"
}
}
]
}
pathMappings 是关键：左边是服务器上 PHP 文件的绝对路径（如 Docker 容器内路径或本地 Apache DocumentRoot），右边是本地项目路径，必须一一对应，否则断点不生效。
启动调试与常见触发方式
VSCode 调试器就绪后，有三种常用方式触发断点：
-
浏览器调试：安装 Xdebug Helper 浏览器插件（Chrome/Firefox），点击图标 → “Debug”，然后访问页面（如
http://localhost/index.php）。URL 会自动带上?XDEBUG_SESSION_START=1 -
CLI 调试：终端中执行
XDEBUG_MODE=debug php script.php（Xdebug 3），VSCode 会自动捕获 -
手动打点：在 PHP 代码中插入
xdebug_break()（Xdebug 2）或xdebug_break();（Xdebug 3 兼容），运行时强制中断
VSCode 左侧调试面板出现堆栈、变量、监视窗口，即可查看上下文、单步跳过/步入/跳出、修改变量值。
排错提示：连不上？先看这三点
调试失败多数卡在连接环节：
-
端口不一致：Xdebug 配置的
client_port和 launch.json 的port必须完全相同（默认 9003，不是旧版的 9000） - 防火墙/IDE 监听未开：确保 VSCode 的调试监听已启动（点击左侧虫子图标 → 点绿色 ▶ 启动“Listen for Xdebug”）
-
路径映射错位：尤其在 Docker 或远程开发场景，
pathMappings左右路径一个字符都不能差；可用xdebug_info()函数输出当前请求的完整文件路径辅助比对
基本上就这些。配置一次，后续项目复制 launch.json 并微调 pathMappings 就能复用，调试效率明显提升。
