phpenv下启用Xdebug必须手动编译安装，因phpenv不管理扩展且pecl易错配PHP路径；需用目标版本的phpize和php-config编译，配置php.ini时须指定绝对路径的zend_extension，并确保Web服务器使用phpenv版本而非系统PHP。
phpenv下启用Xdebug必须手动编译安装，不能靠pecl install
phpenv本身不管理PHP扩展，它只负责切换不同PHP版本的二进制和配置路径。你用phpenv install 8.2.12装完的PHP默认不含Xdebug，pecl install xdebug在phpenv环境下大概率失败——因为pecl依赖的php-config路径常指向系统PHP而非phpenv当前版本，导致.so编译后加载错位。
正确做法是：先用phpenv versions确认当前激活版本（比如8.2.12），再进入该版本源码目录（通常在~/.phpenv/versions/8.2.12/src）重新编译Xdebug：
- 下载对应PHP版本的Xdebug源码（推荐从xdebug.org/download查SHA256匹配）
- 解压后执行：
~/.phpenv/versions/8.2.12/bin/phpize（必须用目标版本的phpize） - 运行：
./configure --enable-xdebug --with-php-config=~/.phpenv/versions/8.2.12/bin/php-config -
make && make install，成功后会输出类似Installing shared extensions: /home/user/.phpenv/versions/8.2.12/lib/php/extensions/no-debug-zts-20220829/
php.ini路径容易搞错：不是/etc/php/，而是phpenv专属路径
phpenv每个PHP版本有独立的php.ini，不在系统全局位置。直接改/etc/php/*/cli/php.ini或/usr/local/etc/php/php.ini完全无效。
必须用以下命令定位真实路径：php --ini | grep "Loaded Configuration File"。正常输出类似：Loaded Configuration File: /home/user/.phpenv/versions/8.2.12/etc/php.ini。这个etc/php.ini才是你要编辑的文件。
立即学习“PHP免费学习笔记（深入）”；
在该文件末尾添加（Xdebug 3.x）：
zend_extension=/home/user/.phpenv/versions/8.2.12/lib/php/extensions/no-debug-zts-20220829/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必须写绝对路径，不能只写xdebug.so；no-debug-zts-20220829这部分会随PHP主版本变化，务必按make install输出的实际路径填写。
CLI调试生效但Web不触发？检查Apache/Nginx是否用了phpenv的PHP
phpenv只影响命令行php命令，不影响Web服务器。如果你用的是系统Apache（如Ubuntu的apache2包），它默认调用/usr/bin/php，跟phpenv无关。
验证方法：phpinfo()页面里看Loaded Configuration File路径，如果显示/etc/php/8.2/apache2/php.ini，说明Web走的是系统PHP，不是phpenv版本。
解决方案分两种：
- 开发阶段建议换用
php -S内置服务器：php -S localhost:8000 -t public/，它100%走phpenv当前PHP，断点立刻生效 - 非要Apache/Nginx，则需卸载系统PHP模块，改用phpenv编译的PHP + FPM：启动
~/.phpenv/versions/8.2.12/sbin/php-fpm，再让Web服务器反向代理到127.0.0.1:9000
VS Code断点不命中？重点核对三个映射关系
即使php -v显示Xdebug、phpinfo()能看到模块、VS Code也监听了9003，断点仍可能失效——根本原因是路径没对齐。
在.vscode/launch.json中，pathMappings必须严格匹配PHP实际执行时的绝对路径。例如：
"pathMappings": {
"/home/user/project": "${workspaceFolder}"
}
这里/home/user/project必须和phpinfo()里SCRIPT_FILENAME值完全一致（比如访问http://localhost/index.php时，该值是/home/user/project/index.php）。差一个字符、大小写不一致、软链接未展开，都会导致VS Code找不到对应文件。
调试时打开xdebug.log，搜索Resolved关键字，能看到Xdebug尝试映射的路径，和你的pathMappings逐字对比——这是最直接的排查方式。
