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 内置服务器）。

在 VSCode 中安装插件并设置 launch.json

安装官方扩展 PHP Debug（由 Felix Becker 提供）。然后在项目根目录创建 .vscode/launch.json，内容如下：

{
  "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 就能复用。