vscode调试php失败90%因xdebug未加载：先执行php -m | grep xdebug确认启用，再检查php.ini中zend_extension路径、xdebug 3配置（如xdebug.mode=debug、client_port=9003）、pathmappings映射方向及php debug插件是否正确安装。
VSCode 调试 PHP 项目失败，90% 是因为 php.ini 根本没加载 Xdebug，而不是 launch.json 写错了。先跑 php -m | grep xdebug，没输出就别往下配了。
确认 Xdebug 是否真被 PHP 加载
这是整个调试链路的起点，跳过这步等于在没通电的插座上插设备。很多用户反复改 launch.json 却始终“连接超时”，其实 PHP 进程压根不知道 Xdebug 存在。
- 运行
php -v，输出里必须含with Xdebug字样；没有？说明扩展未启用 - 运行
php --ini查出实际生效的php.ini路径，别信自己以为在改的那个文件 - 打开该
php.ini，搜zend_extension—— 必须是zend_extension=...，不是extension=... - Windows 下路径含空格（如
C:\Program Files\php\ext\php_xdebug.dll）必须用英文双引号包裹 - 最稳妥方式：访问
phpinfo()页面 → 右键“查看页面源代码” → 粘贴到 Xdebug Wizard，它会给出精确的zend_extension行和版本推荐
php.ini 中 Xdebug 3 的关键参数不能照抄旧版
Xdebug 3 彻底重构了配置体系，xdebug.remote_enable、xdebug.remote_host 这类 2.x 参数已失效，继续写只会让调试静默失败。
-
xdebug.mode=debug是硬性开关，设成develop或漏掉这行，VSCode 永远收不到连接 -
xdebug.start_with_request=yes表示每个 HTTP 请求都尝试连 IDE；若设为trigger，就得手动加?XDEBUG_SESSION_START=1，极易遗漏 -
xdebug.client_port=9003是 Xdebug 3 默认端口，launch.json里的port必须与之严格一致 -
xdebug.client_host在多数本地环境填127.0.0.1即可；但 macOS Monterey+ 或 Docker Desktop 场景下，得改成宿主机网关（如10.0.2.2），否则连接被拒绝 - 加一行
xdebug.log="/tmp/xdebug.log"（Linux/macOS）或xdebug.log="C:\xdebug.log"（Windows），日志能直接暴露连接被拒、路径找不到等真实原因
launch.json 的 pathMappings 映射必须“服务器视角”
断点显示“未绑定”但控制台无报错？八成是 pathMappings 左右两边填反了，或者左边填的是你本地路径而非 PHP 进程看到的路径。
- 左边是 PHP 执行时的绝对路径：Docker 容器内是
/app，XAMPP 是C:\xampp\htdocs，MAMP 是/Applications/MAMP/htdocs，WSL Apache 是/var/www/html - 右边是 VSCode 当前打开的项目路径，用
${workspaceFolder}即可，不要手写绝对路径 - 常见错误：
"pathMappings": { "${workspaceFolder}": "/var/www/html" }—— 映射方向反了，VSCode 找不到对应文件 - 本地用 PHP 内置服务器（
php -S）且路径简单，可暂时省略pathMappings；但只要涉及 Web 服务器或容器，就必须显式配置 - 修改后务必重启 Web 服务或 PHP-FPM，
php.ini变更不会热加载
PHP Debug 插件与调试启动流程的隐性依赖
VSCode 自身不处理 Xdebug 协议，全靠 “PHP Debug” 插件（作者 Felix Becker）解析通信。装错插件或路径指向错误 PHP，调试会卡在“Listening on port 9003”却无响应。
- 必须安装官方维护的 PHP Debug（不是 PHP Intelephense，也不是其他名字相近的插件）
- 按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS）→ 输入PHP: Select Interpreter→ 选中那个你确认过php -m | grep xdebug有输出的 PHP 可执行文件 - 如果系统有多个 PHP（如 Homebrew、XAMPP、Docker），
php.debug.executablePath设置错误会导致 VSCode 启动的是另一个没装 Xdebug 的 PHP - 浏览器访问时，建议配合 Xdebug Helper 浏览器插件（Chrome/Firefox 均有），点击图标启用 Debug 模式，比手动拼 URL 可靠得多
- 启动调试前，确保 VSCode 底部状态栏显示
Listening on port 9003；若显示Port 9003 is already in use，说明有残留进程或别的服务占用了端口
真正卡住人的地方，往往不在 launch.json 的 JSON 语法，而在于 php.ini 里那行 zend_extension 是否指向了正确的 .dll/.so，以及 pathMappings 左边是否真的是 PHP 进程读取文件时看到的路径——这两个点一旦错位，VSCode 就像在等一个永远不会敲门的人。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
