Xdebug与PHP版本必须严格匹配，PHP 8.0+用Xdebug 3.x、7.4及以下用2.9.x；pathMappings路径映射必填且方向正确；需通过Xdebug Helper插件或手动参数触发调试；端口、host配置须双向连通。
PHP版本和Xdebug扩展必须匹配
装了Xdebug但VSCode里断点灰掉、没反应，八成是版本不兼容。PHP 8.0+ 要用 Xdebug 3.x，PHP 7.4 及更早得用 Xdebug 2.9.x —— 混搭直接失效，连xdebug_info()都报错或不输出。
- 运行
php -v和php -m | grep xdebug确认PHP和Xdebug版本 - 查官方支持表：
https://xdebug.org/docs/compat，别信第三方博客的“通用配置” - Windows下用TS（Thread Safe）版PHP，就配TS版Xdebug；Linux常见的是NTS，配错.so文件加载直接失败
- 确认
php.ini里只启用一个xdebug.so（或php_xdebug.dll），重复加载会静默失败
VSCode的launch.json必须设对pathMappings
断点能命中但变量全是undefined，或者跳转到错误文件，基本是路径映射没对齐。Xdebug传的是服务器上的绝对路径（比如/var/www/html/index.php），而VSCode打开的是本地路径（比如C:\project\index.php），中间差一层“怎么翻译”。
-
pathMappings不是可选项，是必填项；空对象{}或写错键名（比如写成pathMapping）会导致整个调试会话降级为“仅连接不映射” - 典型写法：
"pathMappings": { "/var/www/html": "${workspaceFolder}" }—— 左边是服务器路径，右边是本地路径，顺序反了就找不到文件 - Docker场景下，如果PHP容器挂载了
/app，那左边就得写/app，不是宿主机路径 - 用
xdebug.log日志确认映射是否生效：日志里出现Resolved to ...才算成功
Chrome插件和Xdebug Helper要配合触发
断点一直不触发，不是VSCode没配好，而是请求根本没带Xdebug所需的XDEBUG_SESSION_START=PHPSTORM（或任意值）。VSCode不主动发这个，得靠浏览器侧激活。
- 装官方
Xdebug Helper插件（Chrome/Firefox都有），右键图标选“Debug”，别用“Profile”或“Off” - 插件默认发送
XDEBUG_SESSION_START=PHPSTORM，VSCode里launch.json的ideKey必须跟它一致（默认就是PHPSTORM） - 如果改过
ideKey（比如改成VSCODE），插件设置里也得同步改，否则Xdebug收不到指令，安静如鸡 - 命令行调用
curl或API测试时，手动加?XDEBUG_SESSION_START=PHPSTORM参数，不然不会进调试模式
监听端口被占用或防火墙拦截最常被忽略
VSCode显示“正在等待Xdebug连接”，但永远等不到——大概率是port: 9003（Xdebug 3默认）被其他进程占了，或者Docker/WSL里端口没暴露出来。
立即学习“PHP免费学习笔记（深入）”；
- 检查端口占用：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - Windows上IIS或Skype可能霸占9003，换端口更省事：Xdebug里设
xdebug.client_port=9009，VSCode里launch.json同步改port字段 - WSL2用户注意：
xdebug.client_host不能写localhost，得写Windows宿主机IP（如172.28.16.1），用cat /etc/resolv.conf查nameserver那一行 - Docker里跑PHP，确保
docker run加了-p 9003:9003，且PHP容器能反向连回宿主机（xdebug.client_host设对）
client_host和client_port是双向通路，一边不通，整个链路就断在半路；很多人只盯着VSCode配，忘了PHP进程本身能不能“反向拨号”回来。 
