VS Code使用PHP Debug插件配合Xdebug的完整教程-php教程-PHP中文网

必须用xdebug 3，php.ini与launch.json的端口、模式、路径映射须严格一致；验证需执行php -v（含xdebug v3.x）、php --ini（确认配置文件路径）、php --ri xdebug（mode含debug且supports phpinfo()为enabled）；最小配置含zend_extension=xdebug、xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_port=9003、xdebug.idekey=vscode；launch.json须用插件生成并仅改port和pathmappings；触发调试需url加?xdebug_session_start=1或xdebug helper插件激活。

vs code使用php debug插件配合xdebug的完整教程

VS Code 调试 PHP 必须用 Xdebug 3（2026 年已全面弃用 Xdebug 2），且 php.ini 和 launch.json 的端口、模式、路径映射三者必须严格一致，差一个字符都会导致“connection refused”或断点不命中。

确认 Xdebug 3 已加载且版本匹配

别信“我装过了”，必须终端里亲手验证：

运行 php -v，输出里必须含 Xdebug v3.x（不是 v2.x，也不是只写“with Xdebug”）
运行 php --ini，确认你改的 php.ini 是 Loaded Configuration File 那行显示的路径（不是 .user.ini 或其他）
运行 php --ri xdebug，检查 Supports phpinfo() 为 enabled，且 mode 字段包含 debug
如果输出为空或报错，说明扩展没加载成功——重点查 zend_extension 路径是否拼错、文件是否存在、是否与 PHP 架构（TS/NTS、x86/x64）不匹配

php.ini 中必须写的 Xdebug 3 配置项

Xdebug 3 默认关闭所有调试能力，只写 zend_extension 不会触发调试。以下是最小可用配置（删掉所有旧版 xdebug.remote_* 参数）：

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.log=/tmp/xdebug.log
xdebug.log_level=7

说明：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

xdebug.start_with_request=trigger 表示需手动触发（如加 ?XDEBUG_SESSION_START=1），比 yes 更安全，避免全站请求都连调试器
xdebug.client_port=9003 是 Xdebug 3 默认端口，9000 是 Xdebug 2 的，混用必失败
xdebug.log 强烈建议开启，连接失败时直接看日志比猜配置快十倍；路径确保 PHP 进程有写权限
若 PHP 运行在 Docker 容器中，xdebug.client_host 应设为 host.docker.internal（Windows/macOS）或宿主机网关 IP（Linux）

VS Code 中 launch.json 的关键字段

必须用 VS Code 插件自动生成模板（「运行」→「打开配置」→ 选 PHP），不要手写空文件。生成后只改这几项：

"port": 9003 —— 必须和 php.ini 中 xdebug.client_port 完全一致
"pathMappings" —— 本地开发可简化为 {"\/": "${workspaceFolder}/"}；若用 Docker，左边填容器内绝对路径（如 "/var/www/html/"），右边填本地项目路径
删掉所有 runtimeExecutable 或 env 相关字段，除非你明确需要 CLI 调试
不要加 "request": "attach"，本地开发一律用 "request": "launch"

常见错误：pathMappings 键值颠倒、路径末尾斜杠不统一（/var/www/html vs /var/www/html/）、用了 Windows 风格反斜杠 \。

触发调试时浏览器和代码要配合

VS Code 点击 ▶️ 启动 “Listen for Xdebug” 后，它只是监听端口，真正触发靠 PHP 请求本身：

浏览器访问时加参数：http://localhost/index.php?XDEBUG_SESSION_START=1（idekey 值必须匹配 xdebug.idekey）
或安装浏览器插件 Xdebug Helper（Chrome/Firefox），切换为 Debug 模式，自动注入 cookie
PHP 代码中也可硬编码触发：xdebug_break();，但仅限临时排障，勿提交到仓库
CLI 脚本调试需额外设环境变量：XDEBUG_CONFIG="idekey=VSCODE client_port=9003" php script.php

最易忽略的一点：Xdebug 3 不再响应 xdebug.remote_autostart=1 这类旧参数，哪怕你写了也无效；一切以 xdebug.mode 和 xdebug.start_with_request 为准。