如何配置Xdebug调试工具以支持PHP8.1环境调试？

本文共计1083个文字，预计阅读时间需要5分钟。

PHP 8.1 安装 Xdebug 时遇到问题，并非下一个 so 文件就完事。核心问题是版本锁定：

用官方 Wizard 确定唯一正确版本

Xdebug 官方安装向导（xdebug.org/wizard）不是可选项，是强制步骤。手动选“Xdebug 3.1 for PHP 8.1”会翻车——它不识别你的具体编译标识。

• 执行 php -i，右键浏览器中 phpinfo() 页面 → “查看网页源代码”，全选复制整页 HTML 源码
• 粘贴到 xdebug.org/wizard，点击 Analyse；它会返回类似：Download xdebug-3.1.6-8.1-vs16-x86_64.dll 的精确链接
• Windows 用户特别注意：若 php -v 显示 NTS，必须选带 nts 的 DLL；Linux/macOS 用户检查 php -i | grep "Architecture"，确认是 x86_64 还是 arm64
• 下载后，别扔进随便一个 ext/ 目录——用 php -r "echo ini_get('extension_dir');" 确认真实路径，再放进去

php.ini 配置必须删光 remote_ 参数

Xdebug 3.1 强制废弃所有 xdebug.remote_* 配置项。