phpenv 本身不升级 PHP，而是通过 phpenv install 编译安装新版本（如 8.3.13），再用 phpenv global、local 或 shell 切换生效；需提前安装依赖，推荐项目级用 phpenv local 并提交 .php-version 文件。
phpenv 本身不提供“升级 PHP 版本”这个动作——它只负责管理已安装的 PHP 版本，真正的版本升级是通过 phpenv install 安装新版本，再用 phpenv global 或 phpenv local 切换过去。你真正要做的不是“升级 phpenv”，而是“用 phpenv 安装并启用更高版的 PHP”。
怎么用 phpenv 安装新 PHP 版本
phpenv 自身不带 PHP 二进制文件，它依赖 php-build 插件从源码编译安装。确保插件已启用（默认 installer 已自动安装）：
- 运行
phpenv install --list查看可安装的版本（如8.3.13、8.2.24） - 执行
phpenv install 8.3.13开始编译安装——这步耗时较长，需提前装好依赖（autoconf、openssl-dev、libxml2-dev等） - 若报错缺少
libsqlite3-dev或oniguruma-dev，按提示补装即可，Ubuntu/Debian 下常用：sudo apt install libsqlite3-dev libonig-dev - 安装成功后，
phpenv versions会显示新增版本，但不会自动切换
切换到新 PHP 版本的三种方式
装完只是“备货”，必须显式切换才能生效。不同场景选不同命令：
-
phpenv global 8.3.13：设为系统默认，所有终端、所有项目都用这个版本（慎用，可能影响其他项目） -
phpenv local 8.3.13：在当前目录生成.php-version文件，只对该目录及子目录生效（推荐用于项目根目录） -
phpenv shell 8.3.13：仅当前终端会话有效，关掉就恢复，适合临时测试
注意：local 和 shell 的优先级高于 global，且 local 的 .php-version 文件会被 Git 跟踪——团队协作时务必提交它，否则别人拉代码后仍跑旧版本。
立即学习“PHP免费学习笔记（深入）”；
phpenv 工具自身要不要更新？
phpenv 核心脚本更新频率低，但 php-build 插件需要定期更新，否则可能无法安装新版 PHP（比如缺失 8.4.x 的构建定义）：
- 更新
php-build：cd $(phpenv root)/plugins/php-build && git pull - 更新 phpenv 本身：
cd $(phpenv root) && git pull - 如果用的是
phpenv-installer安装的，重跑一次安装脚本也行：curl -L https://raw.githubusercontent.com/phpenv/phpenv-installer/master/bin/phpenv-installer | bash
更新后无需重启 shell，但建议运行 phpenv rehash 刷新 shims 缓存，避免命令找不到。
为什么 phpenv install 失败或卡住？
最常见原因不是网络，而是本地环境缺失或配置冲突：
- macOS 上 Xcode 命令行工具未安装：
xcode-select --install - Linux 上
make或gcc版本太老（PHP 8.3+ 要求 GCC ≥ 10） - 已存在同名版本缓存（比如之前失败中断过）：
rm -rf $(phpenv root)/versions/8.3.13再重试 - 自定义了
PHP_BUILD_CONFIGURE_OPTS但参数错误（如拼错--with-openssl），先 unset 再试
编译日志最后一屏往往有明确报错关键词，比如 error: 'zend_string' undeclared 说明内核头文件不匹配，不是 PHP 本身问题。
