如何在VSCode中配置PHP开发与Xdebug调试？【教程】

需先确认php与Xdebug版本兼容：Xdebug 3须用新配置项（如xdebug.mode=debug），且php.ini中启用zend_extension、设置xdebug.client_port=9003等；vscode仅装PHP Debug插件，launch.json端口与之匹配，并正确配置pathMappings。

确认 PHP 和 Xdebug 版本兼容性

VSCode 本身不运行 PHP，它依赖本地已安装的 php 可执行文件和匹配的 xdebug 扩展。最常踩的坑是版本不兼容：Xdebug 3 不再支持 Xdebug 2 的配置项（如 xdebug.remote_enable），而 VSCode 的 PHP Debug 插件默认适配 Xdebug 3+。先在终端运行：

php -v php -m | grep xdebug

若输出含 Xdebug v3.x，则配置必须用新版参数；若为 v2.x，要么升级 Xdebug，要么在 php.ini 中保留旧参数（但建议升级）。注意 windows 用户需确认 php.ini 是 CLI 模式实际加载的那个（可用 php --ini 查看路径）。

修改 php.ini 启用并监听 Xdebug 3

Xdebug 3 默认不监听外部连接，且默认关闭调试触发。需在 php.ini 中添加或修改以下段落（非注释状态）：

[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

关键点：

立即学习“PHP免费学习笔记（深入）”；

• xdebug.mode=debug 是 Xdebug 3 的启用开关（不是 on 或 1）
• xdebug.start_with_request=yes 表示每次请求自动开始调试（适合 CLI 或简单 Web 场景；Web 开发中也可设为 trigger，配合浏览器插件手动触发）
• xdebug.client_port 必须与 VSCode 的 launch.json 中 port 一致，默认是 9003（Xdebug 2 是 9000）
• xdebug.log 强烈建议开启，出问题时直接查日志比猜快得多

VSCode 安装插件与配置 launch.json

仅安装 PHP Debug（由 Felix Becker 维护）即可，无需其他 PHP 插件辅助调试。安装后，在项目根目录创建 .vscode/launch.json：

{   "version": "0.2.0",   "configurations": [     {       "name": "Listen for Xdebug",       "type": "php",       "request": "launch",       "port": 9003,       "pathMappings": {         "/var/www/html/": "${workspaceFolder}/"       }     }   ] }

注意路径映射：

• 如果用 docker 或 WSL，pathMappings 左侧是容器/远程服务器上的绝对路径，右侧是本地工作区路径
• 纯本地 apache/nginx + Windows，通常可简化为 "${workspaceFolder}/": "${workspaceFolder}/"（但不推荐省略，明确写更稳）
• 没配 pathMappings 会导致断点命中但变量显示 undefined 或跳转错文件

CLI 调试和 Web 调试的区别处理

CLI（命令行）调试直接按 F5 启动即可；Web 调试需确保请求能连上 Xdebug。常见失败原因：

• Apache/Nginx 配置未启用 php_value xdebug.mode debug（只靠 php.ini 不够，Web SAPI 可能被覆盖）
• 浏览器没带 XDEBUG_SESSION_START=phpstorm（或任意值），且 xdebug.start_with_request 没设为 yes 或 trigger
• 防火墙或杀毒软件拦截了 9003 端口（尤其 Windows Defender）
• 多个 PHP 版本共存时，Web 服务器加载的是另一个 php.ini（检查 phpinfo() 页面里的 Loaded Configuration File）

复杂点在于：Xdebug 日志里出现 Connection to client failed 时，90% 是路径映射或端口不一致；出现 Waiting for connection 却无响应，大概率是客户端（VSCode）根本没监听，或网络层被拦。