确认当前PHP是否加载Xdebug：先运行php -v，若输出含“Xdebug v3.x.x”则已成功加载；再用php --ini定位实际生效的php.ini路径，并检查其中zend_extension和xdebug.mode=debug等Xdebug 3必需配置是否正确。
phpenv 本身不管理 PHP 扩展，它只负责切换不同版本的 PHP 二进制和配置路径。开启 Xdebug 的关键不是改 phpenv，而是确保你当前用的 PHP 版本已编译/安装了 Xdebug，并在该版本对应的 php.ini 中正确配置。
phpenv 下怎么确认当前 PHP 是否加载了 Xdebug
phpenv 切换版本后，PHP 实际加载的配置文件路径可能变化，容易误配到系统全局或旧版本的 php.ini。
- 运行
php --ini查看「Loaded Configuration File」路径，这个才是你要改的文件 - 然后运行
php -m | grep xdebug，有输出说明扩展已加载；没输出 ≠ 没装，可能是没启用或路径错 - 更可靠的方式是
php -v：如果带Xdebug v3.x.x字样，说明已加载成功
常见坑：
-
phpenv global 8.2切了版本，但编辑的是/etc/php.ini（系统级），而实际生效的是~/.phpenv/versions/8.2.12/etc/php.ini -
php -i | grep "xdebug"返回空，但phpinfo()页面里能看到 —— 说明 CLI 和 Web SAPI（如 Apache/FPM）用的不是同一个php.ini，调试时要以 Web SAPI 的配置为准
phpenv + Xdebug 3 的最小有效配置（写入对应版本的 php.ini）
Xdebug 3 不再用 xdebug.remote_*，所有参数名都变了，混用直接失效。
立即学习“PHP免费学习笔记（深入）”；
在 ~/.phpenv/versions/{your-version}/etc/php.ini 末尾追加：
zend_extension=xdebug.so xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003 xdebug.log=/tmp/xdebug.log
注意：
-
zend_extension值必须是真实路径（如/Users/you/.phpenv/versions/8.2.12/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so），不能只写xdebug.so（除非 PHP 启动时自动扫描了扩展目录） -
xdebug.client_port=9003是硬性要求，VS Code / PhpStorm 默认连这个端口；设成9000就会“Connection refused” -
xdebug.log路径要有写权限，日志里一旦出现Connection to client failed，基本就是client_host或防火墙问题
为什么 phpenv 切换 PHP 后 Xdebug 突然不工作了
根本原因：Xdebug 是按 PHP 版本编译绑定的，不是通用插件。
- 你用
phpenv install 8.1安装的 PHP，默认不带 Xdebug -
pecl install xdebug是针对当前phpenv local或global指向的 PHP 版本执行的，换版本就得重装 - 如果用
phpenv install --configure-options="--enable-xdebug"，仅对源码编译有效，且 Xdebug 3 要求 PHP ≥ 7.4，低版本会失败
实操建议：
- 对每个要用 Xdebug 的 PHP 版本，先
phpenv local 8.2，再pecl install xdebug - 安装完立刻检查
php -v，确认输出含 Xdebug 版本 - 再去改该版本专属的
php.ini，别偷懒复用旧配置
Xdebug 的麻烦点不在安装，而在「哪个 php.ini、哪个端口、哪个 IDE 监听、哪个 SAPI 在跑」这四者是否严格对齐。尤其是 phpenv 用户，很容易在多个版本间搞混配置路径和扩展状态——最省事的办法是每次切版后，第一件事就是跑一遍 php --ini && php -v，眼见为实。
