Xdebug 3 握手失败主因是 PHP 进程未连接 VSCode，须先验证 php -m | grep xdebug 有输出；再确认 xdebug.mode=debug、client_port=9003、client_host 正确，且 pathMappings 严格按“服务器路径→本地路径”映射，并通过 xdebug.log 定位具体失败环节。
Xdebug 3 控制信号握手失败，90% 是 PHP 进程根本没连上 VSCode，不是断点没设对，而是连接阶段就断在了 TCP 层或协议协商前。
php -m | grep xdebug 没输出，就别配 launch.json 了
这是整个链路的起点。VSCode 再准也没用，PHP 进程压根不知道 Xdebug 存在。php -m 输出里必须有 xdebug；没有，说明扩展没加载成功。常见原因：
-
zend_extension路径写错，或用了extension=而非zend_extension= - Windows 下路径含空格但没加英文双引号，比如
zend_extension="C:\Program Files\php\ext\php_xdebug.dll" - 改的是 Apache 的
php.ini，但 VSCode 调试走的是 CLI 环境——运行php --ini看 Loaded Configuration File，改那个文件 - PHP 版本和 Xdebug 扩展不匹配（如 PHP 8.2 用了 PHP 8.1 的
.dll），用php --ri xdebug查版本，或上传phpinfo()页面源码到 Xdebug Wizard 获取精准推荐
xdebug.mode=debug 缺失或拼错，握手直接静默失败
Xdebug 3 彻底废弃 xdebug.remote_enable 等旧参数，xdebug.mode 是硬开关。设成 develop、off、漏写、或写成 on，都会导致调试协议不启动。必须是：
-
xdebug.mode=debug（仅调试）或xdebug.mode=debug,profile（调试+性能分析） -
xdebug.client_port=9003（Xdebug 3 默认端口，不是 9000） -
xdebug.start_with_request=trigger或yes；设为trigger时，必须手动加?XDEBUG_SESSION_START=1，否则无请求触发 -
xdebug.client_host在 Docker 或 macOS Monterey+ 上不能写127.0.0.1，得换成宿主机网关（如10.0.2.2或host.docker.internal）
launch.json 的 port 和 pathMappings 是两个独立雷区
port 错了，VSCode 根本收不到连接请求；pathMappings 错了，断点显示空心圆、点击无效，但控制台可能完全没报错。
立即学习“PHP免费学习笔记（深入）”；
-
"port": 9003必须与xdebug.client_port完全一致；改了端口就得两边同步改 -
pathMappings是“服务器路径 → 本地路径”的映射，左边是 PHP 进程看到的路径（如容器内/app/index.php、WSL 中/var/www/html/），右边是${workspaceFolder}展开后的绝对路径 - 映射反了、斜杠方向错（Windows 用反斜杠但 JSON 要转义）、漏掉末尾斜杠（
/app/≠/app），都会导致路径解析失败 - 多级目录项目（如 Laravel 的
public/index.php入口），映射要覆盖整个入口路径，不能只映射app/
xdebug.log 是唯一能告诉你“为什么连不上”的证据
不看日志，纯靠猜配置，效率极低。加一行：xdebug.log="/tmp/xdebug.log"（Linux/macOS）或 xdebug.log="C:/xdebug.log"（Windows），然后复现一次请求，直接打开日志看最后一行：
- 出现
Connection to '127.0.0.1:9003' failed→ 端口/地址/防火墙问题 - 出现
File name length doesn't match或Could not open file→pathMappings映射失败 - 日志为空或只有初始化内容 →
xdebug.mode没生效，或请求根本没进 Xdebug - 有连接记录但无后续 → VSCode 没监听，检查 PHP Debug 插件是否启用、端口是否被占用
真正卡住的地方，往往不在“怎么设断点”，而在于“Xdebug 连没连上”这个最基础的事实没验证清楚。每次改动后，先跑 php -m | grep xdebug，再看 xdebug.log 最后三行，比反复重配 launch.json 快十倍。
