VSCode写PHP环境太烦？Xdebug调试配置【实战】-VSCode-PHP中文网

vscode调试php断点不触发，主因是php.ini、launch.json与cli环境未对齐；需用php --ini确认cli加载的php.ini路径，确保xdebug 3五项配置正确，且launch.json中port和pathmappings字面级匹配。

vscode写php环境太烦？xdebug调试配置【实战】

VSCode 调试 PHP 断点不触发、红点变空心、变量全显示 undefined，八成不是插件没装对，而是 php.ini、launch.json、CLI 环境三者根本没对齐 —— 尤其用 PHPStudy 时，Web 服务和命令行用的压根不是同一个配置文件。

VSCode 调试走的是 PHP 命令行（CLI）环境，不是 Apache 或 Nginx 的配置。很多人改了 PHPStudy 里 Apache 对应的 php.ini，却完全忘了 CLI 用的是另一个文件。

打开终端（CMD/PowerShell/Terminal），运行 php --ini，看 Loaded Configuration File 那一行路径 —— 这才是你要编辑的文件
运行 php -v，输出里必须含 with Xdebug v3.x；没有就说明扩展根本没加载
运行 php --ri xdebug，检查 Version 行是否显示版本号，且 Supports phpinfo() 是 enabled
如果 php --ri xdebug 输出里还出现 xdebug.remote_host 或 xdebug.remote_port，说明配置混了 Xdebug 2 的废弃参数，得删干净

Xdebug 3 彻底弃用 remote_* 系列参数，写进去不仅无效，还可能让 PHP 启动失败或跳过调试逻辑。只保留且必须写全以下五项：

zend_extension=xdebug（Linux/macOS）或 zend_extension=php_xdebug.dll（Windows），路径要绝对准确，含空格需加引号
xdebug.mode=debug（不是 on、1 或 develop）
xdebug.client_host=127.0.0.1（Docker/WSL 场景下可能需改成宿主机网关，如 10.0.2.2）
xdebug.client_port=9003（Xdebug 3 默认端口，不是旧版 9000）
xdebug.start_with_request=trigger（推荐手动触发，避免无请求时持续连接；设为 yes 则每次请求都连）

改完后重启终端（或整个 VSCode），再跑 php -v 验证。

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

下载

port 错一位、pathMappings 左右路径多一个斜杠或大小写不一致，断点就永远是空心圆 —— VSCode 不报错，只安静忽略。

"port": 9003 必须和 php.ini 中的 xdebug.client_port 完全一致
pathMappings 左边是 PHP 进程看到的绝对路径，比如：
– Docker 容器内："/app/"
– macOS Apache："/Library/WebServer/Documents/"
– WSL："/mnt/c/xampp/htdocs/"（注意正斜杠）
– PHPStudy 本地："D:\phpstudy_pro\WWW\"（Windows 下要用双反斜杠或正斜杠）
右边统一用 "${workspaceFolder}/"，结尾建议带斜杠，避免 POSIX 路径匹配失败

很多人点了“启动 Apache”就以为万事大吉，但 PHPStudy 的 XDebug 开关状态、服务启动顺序、PHP 版本切换后的重载动作，全都影响调试是否生效。

切换 PHP 版本后，必须先停止所有服务 → 再启用 XDebug → 最后重启 Apache，不能只点“重启”
确保 Apache 和 MySQL 都显示绿色运行状态，仅启动其中一项会导致调试会话无法建立
PHPStudy Pro 的“扩展组件”里 XDebug 开关是灰色不可点？说明当前 PHP 版本没内置 XDebug，换一个带 nts 标记的版本（如 php7.4.3nts）
如果用 PHPStudy 自带的 Web 服务，pathMappings 左侧路径必须和它实际托管目录完全一致，比如默认是 D:phpstudy_proWWW，就不能写成 D:/phpstudy_pro/WWW/（Windows 下路径大小写敏感）

最常卡住的地方：你以为改了 PHPStudy 界面里的配置就生效了，其实 CLI 没动；你以为 launch.json 端口写对了就行，其实 pathMappings 左侧路径少了个盘符或多了个空格 —— 这些地方 VSCode 从不提示，只沉默跳过。