Xdebug 3.1在PHP 8.1上需严格匹配版本、模式与环境：必须用官方向导选版，PHP≥8.1.7才兼容；xdebug_start_error_collection()要求mode=develop,debug；step_over退出是3.1.1已知bug，须升至3.1.2+；CLI需绝对路径加载，Web需重启PHP-FPM，VS Code中XDEBUG_TRIGGER须通过请求头或服务器配置传递。
Xdebug 3.1 在 PHP 8.1 上不是“装上就能用”，多数报错根本不是你代码或配置写错了，而是版本、模式、环境三者没对齐。
php --version 不显示 Xdebug 或 Failed loading Zend extension
这是最底层的加载失败，90% 是 DLL/so 文件与 PHP 编译参数不匹配。
- 必须用 Xdebug 官方向导（
php -i输出粘贴到 xdebug.org/wizard）获取精确推荐版本，不能靠“PHP 8.1 就选 xdebug-3.1.x-8.1”这种经验判断 - Windows 下尤其注意：PHP 8.1.0–8.1.6 有已知 zlib 兼容问题，Xdebug 3.1 要求 PHP ≥ 8.1.7；若你的 PHP 是 8.1.5，必须升级 PHP 或降级 Xdebug 到 3.0.4（但会丢失
xdebug_start_error_collection()等新特性） - Linux/macOS 用户用
pecl install xdebug-3.1.6后，检查extension_dir路径是否真实存在该 so 文件，且权限为 644；zend_extension的路径必须是绝对路径，相对路径在 CLI 模式下常静默失效
xdebug_start_error_collection() 报 Call to undefined function
这个函数只存在于 Xdebug 3.1.0 及之后版本，但即使版本对，调用仍会失败——因为功能被 mode 锁死了。
- 运行
php --ri xdebug，确认输出中Mode行显示的是develop,debug，而不是只有debug。仅设xdebug.mode=debug时，xdebug_start_error_collection()直接不可用 - CLI 脚本里必须手动调用，且要在任何错误触发前执行；放在
error_handler回调里调用是无效的——错误已经发生了 - Web 环境下，如果用了 opcache，改完
php.ini后必须重启 PHP-FPM 进程（systemctl restart php8.1-fpm），仅 reload 不生效
调试时 step_over 突然退出，日志出现 stopping reason="ok"
这是 Xdebug 3.1.1 的硬伤，不是你的断点逻辑或 IDE 设置问题。
立即学习“PHP免费学习笔记（深入）”；
- 只要你在用 Xdebug 3.1.1，不管 PHP 版本、IDE 类型、网络环境如何，只要执行 step over / step into 就可能触发该 bug
- 唯一可靠解法是升级到
xdebug-3.1.2或更高（如当前稳定版3.1.6）；降级回 3.0.x 也不行——3.0.x 根本没有xdebug_start_error_collection() - 升级后务必检查
php --ri xdebug输出里的Version行，避免旧 DLL 文件残留导致“看似升级实则没换”
VS Code 或 PhpStorm 连不上，XDEBUG_TRIGGER 不生效
环境变量在 Web 请求里不会自动从 IDE 配置透传过去，这是最常见的误解点。
- 如果你用的是 “Listen for Xdebug” 模式（即无
program字段的 launch.json），env里设XDEBUG_TRIGGER完全无效——VS Code 此时不启动任何 PHP 进程 - 正确做法是：在浏览器加请求头
XDEBUG_TRIGGER: 1（配合 Xdebug Helper 插件），或在 Nginx/Apache 配置里显式设置环境变量（如 Nginx 的fastcgi_param） - 宝塔用户注意：
xdebug.client_host不能填localhost，要填宿主机 IP（如开发机是 Windows，填10.0.2.2）；Docker 环境统一用host.docker.internal
真正卡住人的从来不是“怎么配”，而是“哪个环节在悄悄覆盖你的配置”——PHP-FPM pool 配置、宝塔面板的额外 ini 文件、Docker 的覆盖层、甚至 IDE 自带的 xdebug.ini 注入，都可能让 php --ini 显示的加载顺序和实际生效顺序不一致。动手前先跑一遍 php --ri xdebug，盯着 Mode、Version、Loaded Configuration File 这三行看，比反复改配置高效得多。
