VSC怎么配置PHP的Xdebug_远程调试设置步骤【详解】

需先确认Xdebug版本为3.x并启用调试模式，再配置php.ini中zend_extension、xdebug.mode=debug、xdebug.client_host、xdebug.client_port=9003及xdebug.log，最后在VS Code中安装PHP Debug插件并正确设置launch.json的port和pathMappings。

确认 Xdebug 版本和 PHP 运行模式

VS Code 本身不运行 PHP，它依赖本地或远程的 PHP 环境 + Xdebug 扩展。先在终端执行 php -v 和 php -m | grep xdebug，确认 Xdebug 已加载。注意：Xdebug 3 和 Xdebug 2 的配置项完全不同，且 Xdebug 3 默认不兼容旧版 IDE 配置。若输出中含 Xdebug v3.x，后续所有 zend_extension 路径、xdebug.mode、xdebug.client_host 等必须按 v3 规范写；若仍是 v2，需停用并升级，因为 VS Code 的 PHP Debug 插件已不再维护对 Xdebug 2 的兼容支持。

修改 php.ini 启用远程调试（Xdebug 3）

找到正在使用的 php.ini（用 php --ini 查），在末尾添加以下内容（根据实际环境调整）：

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

关键点：

• xdebug.mode=debug 是 Xdebug 3 的必需开关，仅设 zend_extension 不会启动调试
• 本地开发时 xdebug.client_host 通常为 127.0.0.1；若 PHP 运行在 Docker 容器内且 VS Code 在宿主机，这里要填宿主机网关（如 host.docker.internal 或 172.17.0.1）
• 端口必须与 VS Code 中 launch.json 的 port 一致，默认是 9003（Xdebug 2 是 9000）
• xdebug.log 强烈建议开启，出问题时直接看日志比猜配置快得多

VS Code 安装插件并配置 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 必须与 php.ini 中的 xdebug.client_port 完全一致
• pathMappings 是远程调试的核心映射：左边是服务器上 PHP 文件的绝对路径（如 Docker 内 /var/www/html/index.php），右边是本地对应文件夹（${workspaceFolder} 即 VS Code 当前打开的文件夹）
• 如果 PHP 在远程服务器（非 Docker），且你用 SFTP 同步代码，pathMappings 左边应填远程服务器上的真实路径，如 /home/user/project/

启动调试并验证断点是否生效

启动调试前务必：

• 重启 Web 服务或 PHP-FPM（sudo systemctl restart php-fpm 或 sudo service apache2 restart）使 php.ini 生效
• 在 VS Code 中点击左侧调试图标 → 选择 Listen for Xdebug → 点击绿色 ▶️ 启动监听
• 在 PHP 文件中打一个断点（如 index.php 第一行），然后在浏览器访问该 URL（如 http://localhost/index.php）

如果断点未命中，立刻检查 /tmp/xdebug.log：常见错误包括连接被拒绝（端口不匹配）、路径映射失败（Could not map file）、Xdebug 尝试连错 IP（如连了 127.0.0.1 但实际需连宿主机 IP）。Docker 用户最容易卡在 client_host 配置上——容器里 127.0.0.1 指自己，不是宿主机。