PHP 5.6仅支持Xdebug 2.x（如2.5.5、2.9.8），Xdebug 3.x因Zend Engine API断裂完全不兼容；必须用phpinfo()源码通过xdebug.org/wizard.php精准匹配下载，并严格使用xdebug.remote_*等Xdebug 2配置项。
PHP 5.6只能用Xdebug 2.x，Xdebug 3.x完全不兼容
PHP 5.6 无法加载任何 Xdebug 3.x 版本——不是“配置不对”，是底层 ZE（Zend Engine）API 已断裂。Xdebug 3 强制要求 PHP 7.2+，而 Xdebug 2.9.8 是最后一个支持 PHP 5.6 的正式版本。如果你执行 php -v 输出类似 PHP 5.6.40，就别试 xdebug-3.1.5.so 或 php_xdebug-3.0.4.dll，它们会直接导致 Invalid library 错误或 zend_extension 加载失败，php --ini 里也看不到扩展生效。
- 确认 PHP 主版本：运行
php -v，只看第一段数字（如5.6.40→ 属于 PHP 5.6 系列） - 查 Xdebug 官网下载页（
https://xdebug.org/download），在 “PHP 5.6” 标题下找xdebug-2.5.5、xdebug-2.9.8这类带.2.x后缀的包 - Windows 用户注意 TS/NTS 和架构：PHP 5.6 常见为 VC11 + NTS（非线程安全），对应文件名类似
php_xdebug-2.5.5-5.6-vc11-nts.dll；用错类型会导致 Apache 启动失败 - macOS/Linux 用户若用 Homebrew/MacPorts，优先走
sudo port install php56-xdebug或pecl install xdebug-2.5.5，避免手动找.so路径
phpinfo()输出必须完整粘贴到 xdebug.org/wizard.php
靠猜版本号下载 Xdebug 几乎必踩坑。PHP 5.6 有多个 ABI（Application Binary Interface）变体：不同编译参数（ZTS/NTS）、不同 VC 版本（VC9/VC11/VC14）、不同架构（x86/x64）都会生成互不兼容的 .dll 或 .so。官方 wizard.php 是唯一可靠入口——它解析 phpinfo() 输出里的 Compiler、Architecture、Zend Extension Build 等字段，精准匹配。
- 新建
info.php，内容只有<?php phpinfo(); ?> - 浏览器访问该文件 → 右键「查看网页源代码」→ 全选复制全部 HTML 源码（不是页面上渲染出的文字）
- 粘贴到
https://xdebug.org/wizard.php→ 提交后它会明确告诉你该下哪个文件、怎么配php.ini - 如果 wizard 显示 “Xdebug does not support your version of PHP”，说明你用的是 PHP 5.6 但环境里实际跑的是 PHP 7+ 的
php命令（常见于多版本共存未切对）
Xdebug 2 配置项不能照搬 Xdebug 3 的写法
Xdebug 2 和 3 的 INI 配置命名完全不同，混用会导致静默失效。例如 xdebug.mode=debug 在 Xdebug 2 下是非法配置项，会被忽略；而 Xdebug 2 的 xdebug.remote_autostart=1 在 Xdebug 3 中已废弃，设了反而报错 Unknown configuration setting。PHP 5.6 必须严格使用 Xdebug 2 的配置风格。
- 必需启用项（Xdebug 2）：
xdebug.remote_enable=1、xdebug.remote_handler=dbgp、xdebug.remote_host=127.0.0.1、xdebug.remote_port=9000 - 推荐关闭性能敏感项：
xdebug.auto_trace=0、xdebug.profiler_enable=0（开启后每个请求都写磁盘，PHP 5.6 下极易超时） - IDE key 统一设为
PHPSTORM或VSCODE，和 IDE 里设置保持一致；VS Code 的launch.json中"ideKey"字段必须匹配 - 路径映射（path mapping）在 IDE 中必须 1:1 对齐：服务器上的
/var/www/html/要映射到本地项目根目录，少一个斜杠或大小写错误，断点就永远不命中
Docker 或远程服务器上调试失败，大概率是 host.docker.internal 解析失败
PHP 5.6 容器内启用 Xdebug 2 时，xdebug.remote_host 不能写 localhost 或 127.0.0.1——那会让 PHP 尝试连容器自己的 9000 端口，而非宿主机 IDE。旧版 Docker for Mac/Windows 支持 host.docker.internal，但 Linux 上默认不提供该 DNS 名。硬编码宿主机真实 IP（如 192.168.1.100）又不通用。
立即学习“PHP免费学习笔记（深入）”；
- Linux Docker 用户：启动容器时加
--add-host=host.docker.internal:host-gateway - Mac/Windows 用户：确认 Docker Desktop 设置中启用了
Use the Docker Host from inside the container（新版默认开） - 远程服务器（非 Docker）：
xdebug.remote_host必须填你本机公网/局域网 IP，并确保本机防火墙放行 9000 端口（ufw allow 9000或 Windows Defender 入站规则） - 验证连通性：进容器执行
nc -zv host.docker.internal 9000，返回succeeded才算通；否则断点必然失败，且无明显报错
xdebug_info() 依然显示“enabled”，但 IDE 就是收不到连接。每次改完配置，务必用 php --ri xdebug 确认模块加载成功，再用 telnet 或 nc 实测端口连通，别只盯着浏览器里 phpinfo 的小绿块。 
