xdebug在php 8.1上需严格对齐版本、模式与加载路径：php必须≥8.1.7才兼容xdebug 3.1，须用官方向导选版；cli需绝对路径加载，web需重启php-fpm；xdebug_start_error_collection()要求mode=develop,debug且提前调用。
Xdebug 在 PHP 8.1 上不是配几个参数就能跑起来的，绝大多数“断点不触发”“连不上 IDE”“函数报错未定义”，根源都在版本、模式、加载路径三者没对齐——尤其是 PHP 8.1.0–8.1.6 有 zlib 兼容缺陷，Xdebug 3.1 要求最低 PHP 8.1.7。
php -v 不显示 Xdebug 或 Failed loading Zend extension
这是最底层的加载失败，90% 是 xdebug.so（Linux/macOS）或 php_xdebug.dll（Windows）与当前 PHP 编译参数不匹配。
- 必须用 Xdebug 官方向导：运行
php -i，复制全部输出，粘贴到向导页面，它会给出唯一推荐的下载链接和精确的zend_extension=行 - Windows 下特别注意：PHP 8.1.0–8.1.6 无法加载 Xdebug 3.1.x，必须升级 PHP 至 ≥8.1.7，或降级 Xdebug 到 3.0.4（但会丢失
xdebug_start_error_collection()等特性） - Linux/macOS 用户用
pecl install xdebug-3.1.6后，检查extension_dir路径下是否真实存在该文件，且权限为 644；zend_extension的值必须是绝对路径，相对路径在 CLI 模式下常静默失效
xdebug_start_error_collection() 报 Call to undefined function
这个函数只存在于 Xdebug 3.1.0+，但即使版本对，调用仍会失败——因为功能被 xdebug.mode 锁死了。
- 运行
php --ri xdebug，确认输出中Mode行显示的是develop,debug，而不是只有debug；仅设xdebug.mode=debug时该函数不可用 - CLI 脚本里必须手动调用
xdebug_start_error_collection()，且要在任何错误触发前执行；放在set_error_handler回调里调用是无效的——错误已经发生了 - Web 环境下，如果启用了
opcache，改完php.ini后必须重启 PHP-FPM（如systemctl restart php8.1-fpm），仅 reload 不生效
VS Code / PhpStorm 连不上，XDEBUG_TRIGGER 不生效
Xdebug 3 默认关闭远程调试，且不再识别 xdebug.remote_* 类参数，混用旧配置会导致静默失效。
- 确保
php.ini中只保留新参数体系：xdebug.mode=debug、xdebug.start_with_request=trigger（或）、<code>xdebug.client_host=127.0.0.1（Docker 用host.docker.internal）、xdebug.client_port=9003 -
launch.json中的pathMappings必须是“PHP 进程看到的路径 → VS Code 打开的路径”，例如 WSL 下 Apache DocumentRoot 是/var/www/html，而项目在/home/user/project，就得写"/var/www/html": "${workspaceFolder}" -
XDEBUG_TRIGGER不是靠浏览器插件自动带上的——它必须通过请求头（如XDEBUG_SESSION: 1）或服务器配置（如 Nginx 的fastcgi_param HTTP_XDEBUG_SESSION "1";）显式传递；URL 参数?XDEBUG_SESSION_START=1仅在xdebug.start_with_request=trigger时有效
step_over 突然退出，日志出现 stopping reason="ok"
这是 Xdebug 3.1.1 的已知硬伤，不是你的断点逻辑或 IDE 设置问题。只要你在用 3.1.1，不管环境如何，step over / step into 都可能无征兆退出。
- 唯一可靠解法是升级到
xdebug-3.1.2或更高（如当前稳定版3.1.6）；降级回 3.0.x 也不行——3.0.x 根本没有xdebug_start_error_collection() - 升级后务必运行
php --ri xdebug，检查Version行是否更新，避免旧.so文件残留导致“看似升级实则没换” - CLI 脚本调试时，
xdebug.mode必须包含debug，且xdebug.client_host要能被 PHP 进程解析（比如 macOS Monterey+ 或 Docker Desktop 下可能得设为10.0.2.2而非127.0.0.1）
最易被忽略的点：PHP CLI 和 Web SAPI（如 FPM/Apache）往往加载不同的 php.ini，调试时要以 Web SAPI 的配置为准；php -m 和 phpinfo() 输出不一致，基本就是这个原因。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
