17370845950

VS Code 调试 PHP 必须同时配置 Xdebug 3（PHP 端）和 PHP Debug 插件（VS Code 端），关键在于 php.ini 中启用 zend_extension、设置 xdebug.mode=debug 与 client_port=9003，并在 launch.json 中匹配 port 和 pathMappings。

VS Code 能调试 PHP，但不是开箱即用——必须同时配对 Xdebug 3（PHP 端）和 PHP Debug 插件（VS Code 端），缺一不可。断点不触发、连接超时、变量为空，90% 都是这两端配置没对齐。

确认 Xdebug 3 已正确加载并监听本地

这是整个流程的地基。很多人卡在“点了 F5 没反应”，其实 VS Code 根本没收到连接请求。

• 终端运行 php -m | grep xdebug，有输出才说明扩展已启用；无输出就别往下走了
• 检查 php.ini（用 php --ini 找准确路径），Xdebug 3 必须用以下写法（不是旧版的 xdebug.remote_enable=1）：

[xdebug]
zend_extension=xdebug
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.client_port=9003 是关键，默认值，VS Code 插件也默认连这个端口；若改了，两边必须同步改
• 重启 Web 服务（Apache/Nginx）或 PHP 内置服务器；Windows 用户若用 phpstudy/XAMPP，请在控制面板里「重启服务」而非只重启 Apache

VS Code 中装对插件 + 配准 launch.json

只装「PHP」扩展不够，它只提供语法高亮和跳转；真正收 Xdebug 连接的是 PHP Debug 插件（作者：felixfbecker）。

• 在扩展市场搜 PHP Debug，安装后重启 VS Code
• 打开项目根目录 → 按 F5 → 选 PHP → 自动生成 .vscode/launch.json
• 重点改两项：port 和 pathMappings，其余保持默认即可

{
  "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，XAMPP 是 C:/xampp/htdocs），右边是你的本地项目文件夹；映射错一个字符，断点就永远不命中

触发调试：URL 参数 or CLI 脚本？怎么选

两种方式本质一样，都是让 PHP 主动连回 VS Code。区别在于你当前开发场景。

• Web 请求调试（推荐）：访问 http://localhost/index.php?XDEBUG_SESSION_START=1，或装浏览器插件「Xdebug Helper」自动加参数
• CLI 脚本调试（适合命令行工具）：在 launch.json 中额外加一个配置：

{
  "name": "Launch currently open script",
  "type": "php",
  "request": "launch",
  "program": "${file}",
  "cwd": "${fileDirname}",
  "port": 9003
}

• 然后打开 test.php → 按 F5 → 选这个配置 → 就会直接执行该脚本并进断点
• 注意：CLI 方式下 xdebug.start_with_request=yes 仍需开启，否则不触发

断点生效但变量看不到？别急着重装

常见现象：程序停在断点，调用堆栈正常，但「变量」面板空空如也，或显示 undefined。

• 先看右下角状态栏：是否显示 Xdebug listening on 127.0.0.1:9003？没显示说明监听根本没起来
• 打开 xdebug.log（按配置路径找），搜索 Connection failed 或 Failed to connect，大概率是防火墙拦截、Docker 网络不通、或 client_host 写成了 localhost（某些系统解析失败，必须用 127.0.0.1）
• 如果用 Docker，xdebug.client_host 不能写 127.0.0.1（那是容器自己），得填宿主机 IP（如 172.17.0.1），且 pathMappings 左边必须是容器内路径

最常被忽略的一点：Xdebug 日志默认不开启，而它是唯一能告诉你“到底连没连上”的证据。只要调试异常，第一反应不是重装，而是打开 xdebug.log 看第一行错误。