VS Code 配置 Xdebug 调试 PHP 的核心是三步：安装启用 Xdebug 扩展、正确配置 php.ini（注意 Xdebug 2/3 版本差异及端口 9003）、VS Code 中设置匹配的 launch.json（含 port 和 pathMappings）。
在 VS Code 中配置 Xdebug 调试 PHP 应用，核心是三步：安装并启用 Xdebug 扩展、配置 php.ini 使其与 VS Code 通信、在 VS Code 中设置正确的调试环境。只要每步对齐版本和端口，基本不会卡住。
确认 PHP 和 Xdebug 版本兼容
Xdebug 3 与 Xdebug 2 配置差异很大，务必先查清你用的是哪个版本。在终端运行：
php -v | grep xdebug或创建一个 info.php 文件，写入 <?php phpinfo(); ?>，浏览器打开后搜索 “xdebug”。若显示 “Xdebug v3.x”，就按 Xdebug 3 方式配；若为 “Xdebug v2.x”，请跳过 Xdebug 3 的配置项。
修改 php.ini 启用并配置 Xdebug
找到你的 php.ini 文件（用 php --ini 查路径），在末尾添加以下内容（以 Xdebug 3 为例）：
立即学习“PHP免费学习笔记（深入）”；
Linux 性能分析与调优专家，覆盖 CPU、内存、磁盘 I/O、网络、内核参数、编译优化、容器/K8s。适用场景：系统卡顿/高负载、内存不足/OOM/Swap 高、CPU 异常/iowait 高。
-
zend_extension=xdebug（Linux/macOS 下通常为
xdebug.so，Windows 为php_xdebug.dll，路径需写绝对路径或确保在扩展目录） - xdebug.mode=debug
- xdebug.start_with_request=yes（让每次请求自动触发调试，开发时更省事）
- xdebug.client_host=127.0.0.1（VS Code 运行在本机时填这个）
-
xdebug.client_port=9003（Xdebug 3 默认端口，不是 9000；VS Code 的
launch.json必须匹配） - xdebug.log=/tmp/xdebug.log（可选，出问题时查日志定位连接失败原因）
改完重启 Web 服务器（如 Apache 或 PHP Built-in Server）或 PHP-FPM。
在 VS Code 中安装插件并配置 launch.json
安装官方扩展 PHP Debug（由 Felix Becker 提供）。然后在项目根目录下建文件夹 .vscode，新建 launch.json，内容如下：
注意：
- port 必须和 xdebug.client_port 一致
- pathMappings 是关键：左边是服务器上 PHP 文件的绝对路径（如 Docker 容器内或远程服务器路径），右边是本地项目路径。本地开发常见情况是两边相同，可写成 "${workspaceFolder}": "${workspaceFolder}"；若用 Docker，左边填容器内路径，比如 "/app"
开始调试：打断点 → 启动监听 → 触发请求
在 PHP 文件中点击行号左侧设断点（红点），然后点击 VS Code 左侧调试图标 → 顶部选择 “Listen for Xdebug” → 点绿色 ▶️ 启动监听。此时底部状态栏应显示 “Xdebug listening on port 9003”。
接着访问你的 PHP 页面（如 http://localhost:8000/index.php），页面会暂停，VS Code 自动跳转到断点处，变量、堆栈、监视表达式全可用。
如果没反应，先检查 Xdebug 日志是否报 “connection refused”，再确认 PHP 是否真加载了 Xdebug（php -m | grep xdebug），最后核对端口和 pathMappings。
基本上就这些。不复杂但容易忽略路径映射和端口一致性。
