VSCode调试PHP失败90%因xdebug.client_port与launch.json的port不一致或pathMappings路径错误；须确认Xdebug 3配置（禁用remote_*参数）、端口统一为9003、pathMappings字面级对齐、CLI与Web共用同一php.ini，并通过xdebug.log定位连接问题。
VSCode 调试 PHP 失败，90% 是因为 xdebug.client_port 和 launch.json 中的 port 不一致，或者 pathMappings 指向了不存在/不匹配的路径——不是插件没装好，而是两端“说的不是同一种地址语言”。
确认你用的是 Xdebug 3（而不是混用 v2 配置）
Xdebug 3 彻底废弃了 xdebug.remote_enable 这类旧参数，写进去不仅无效，还可能导致 PHP 启动失败或静默跳过调试逻辑。
- 在终端运行
php -v，输出里必须含Xdebug v3.x字样 - 再执行
php --ri xdebug，检查Version行和Supports phpinfo()是否为 enabled - 如果看到
xdebug.remote_host或xdebug.remote_port出现在配置列表里，说明你当前加载的 php.ini 里还残留着 Xdebug 2 的配置，得删干净 - 只保留这些核心项（全部写在 php.ini 末尾即可）：
zend_extension=xdebug<br>xdebug.mode=debug<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003<br>xdebug.start_with_request=trigger
launch.json 的 port 和 pathMappings 必须“字面级对齐”
port 错一个数字、pathMappings 左右路径多一个斜杠或大小写不一致，断点就永远是空心圆。
-
port值必须和xdebug.client_port完全相同（Xdebug 3 默认是9003，不是旧版的9000） -
pathMappings左侧是 PHP 实际运行时看到的**绝对路径**，比如：
– Docker 容器内："/var/www/html/"
– macOS Apache："/Library/WebServer/Documents/"
– Windows WSL："/mnt/c/xampp/htdocs/"（注意用正斜杠） - 右侧统一用
"${workspaceFolder}/"，结尾带斜杠；左侧也建议统一加尾部斜杠，避免 POSIX 路径匹配失败 - 本地开发（不用 Docker / 远程）且 PHP 用内置服务器（
php -S）时，可省略pathMappings；但只要涉及 Apache/Nginx/FPM，就必须显式配置
PHP CLI 加载的 php.ini 路径必须和 Web 服务一致
VSCode 调试依赖 CLI 模式下的 PHP 环境，而你浏览器访问时走的是 Apache 或 FPM —— 如果两者加载的不是同一个 php.ini，Xdebug 就只在一边生效。
立即学习“PHP免费学习笔记（深入）”；
- 先跑
php --ini，看Loaded Configuration File路径；记下这个文件 - 再跑
php -m | grep xdebug，确认输出非空；如果为空，说明 Xdebug 没在这个 ini 里启用 - Windows 用户特别注意：WAMP/XAMPP 通常有两套
php.ini（Apache 目录下一套，PHP 目录下一套），CLI 默认读后者；改完要重启 VSCode 终端才能生效 - macOS/Linux 用户若用 Homebrew 安装 PHP，路径通常是
/usr/local/etc/php/X.Y/php.ini，别去改系统级的/etc/php.ini
调试启动后没反应？先查 xdebug.log
比对着文档反复检查配置，不如直接看 Xdebug 自己记的日志——它会明确告诉你连谁、为什么连不上、卡在哪一步。
- 在 php.ini 里加上这一行：
xdebug.log="/tmp/xdebug.log"（Linux/macOS）或xdebug.log="C:\temp\xdebug.log"（Windows） - 触发一次页面访问（如
http://localhost/index.php?XDEBUG_SESSION_START=1） - 立刻打开日志文件，搜索
ERROR或Failed to connect；常见提示如：
–Failed to connect to client (xx.xx.xx.xx:9003)→ 防火墙/端口被占/VSCode 没监听
–Could not open file '/var/www/html/index.php'→pathMappings左侧路径错
–Client sent 'stop' message→ 连上了但脚本很快结束，可能断点设在未执行分支
最易被忽略的一点：VSCode 的调试监听是单次有效的。F5 启动后，它只等**下一个**符合条件的 Xdebug 连接；如果浏览器已发过请求、或你中途关掉了监听，就得重新按 F5 —— 它不会后台常驻等待，这点和传统 IDE 不同。
