VSCode调试PHP失败主因是php.ini与launch.json配置错位：需确保php -v和php -m验证Xdebug已加载，xdebug.mode=debug、client_port=9003与launch.json的port一致，pathMappings字面级对齐路径，且禁用Xdebug 2旧参数。
VSCode 本身不执行 PHP，调试失败几乎全是路径、端口或模式配置错位导致的——不是插件没装对，而是 php.ini 和 launch.json 没对齐。
确认 PHP 解释器和 Xdebug 已就位
这是所有调试的前提。VSCode 不会帮你装 PHP，也不会自动加载 Xdebug；它只负责转发请求、展示变量。必须先在终端里验证基础环境：
- 运行
php -v，确认输出包含版本号（如PHP 8.3.14），且无“not found”错误 - 运行
php --ini，记下 Loaded Configuration File 路径，比如C: mppphpphp.ini - 运行
php -m | findstr xdebug（Windows）或php -m | grep xdebug（macOS/Linux），有输出才说明扩展已加载 - 若无输出，别急着配 VSCode——先去
php.ini里检查zend_extension路径是否指向真实存在的.dll或.so文件
php.ini 中 Xdebug 3 的关键配置项
Xdebug 3 默认关闭所有调试能力，漏掉任意一个开关，断点就会静默失效。以下配置必须全部存在且值准确：
-
xdebug.mode = debug—— 总开关，没有它，其他参数全无效 -
xdebug.start_with_request = yes—— 让每次 HTTP 请求都尝试连接调试器，避免手动触发 -
xdebug.client_host = 127.0.0.1—— 不能写localhost，DNS 解析延迟会导致连接超时 -
xdebug.client_port = 9003—— 必须和 VSCode 的launch.json中port完全一致；XAMPP/PHPStudy 默认可能是9000，得手动改 -
xdebug.log = C:/tmp/xdebug.log（Windows）或/tmp/xdebug.log（macOS/Linux）—— 出问题时第一手线索，日志末尾出现Connection to debugging client failed就说明 VSCode 没监听或端口不通
VSCode 中 launch.json 的 pathMappings 映射规则
断点变灰色？90% 是 pathMappings 没写对。VSCode 看到的是你本地项目路径（如 D:myappindex.php），而 PHP 进程看到的是 Web 服务器根目录下的路径（如 C:
mpphtdocsindex.php）。两者不映射，调试器根本找不到对应行。
立即学习“PHP免费学习笔记（深入）”；
- 打开项目根目录 →
.vscode/launch.json→ 找到configurations下的pathMappings字段 - Windows + XAMPP：写成
"C:\xampp\htdocs": "${workspaceFolder}" - Windows + PHPStudy：写成
"D:\phpstudy_pro\WWW": "${workspaceFolder}" - macOS/Linux：用正斜杠，如
"/var/www/html": "${workspaceFolder}" - 即使只调试 CLI 脚本（不走 Web），也必须写；否则
$_SERVER缺失，Laravel/Symfony 等框架初始化会失败
调试启动方式与常见假死现象
F5 按下去没反应、浏览器刷新后断点不触发、调试面板显示 “Waiting for a debug connection…”——这不是 VSCode 坏了，是链路某处卡住了。
- 必须先在 VSCode 调试侧边栏点击
Listen for XDebug（绿色 ▶️），再在浏览器访问页面；顺序反了就收不到连接 - 确保 PHP 进程确实启用了 Xdebug：访问
http://127.0.0.1/phpinfo.php，搜索 “xdebug” 看是否列出完整配置 - 检查防火墙是否拦截了
9003端口（尤其 Windows Defender 防火墙默认阻止入站） - 如果用 PHP 内置服务器（
php -S），需额外加-t指定文档根目录，并确认该目录与pathMappings中的路径一致 - 不要同时开多个调试会话：VSCode 默认只监听一个
9003，第二个会失败且无提示
最易被忽略的一点：Xdebug 版本必须严格匹配 PHP 版本和线程安全类型（TS/NTS）。PHP 8.3 + NTS 就必须用 Xdebug 3.3.x 的 NTS 版本，混用 TS 版本会导致 php -m 不显示 xdebug，且无任何报错——只有日志里写一句 “Failed loading …”。
