phpenv需显式安装各PHP版本后，再通过local/global/shell命令激活；未安装版本无法切换或运行。常见安装失败原因包括依赖缺失、网络限制、未启用php-build插件等。
phpenv 不是“安装一次就自动切换版本”的工具，它必须显式安装每个想用的 PHP 版本，再通过 phpenv local、phpenv global 或 phpenv shell 指令激活对应版本——没安装的版本无法切换，也没法运行。
phpenv install 会失败的常见原因
执行 phpenv install 8.3.13 卡住或报错，通常不是 phpenv 本身的问题，而是依赖缺失或网络策略限制：
- 缺少编译工具链：Ubuntu/Debian 需先装
build-essential、autoconf、automake、libtool-bin；macOS 需 Xcode Command Line Tools（xcode-select --install） - 缺少扩展依赖库：比如装带 OpenSSL 的 PHP，得先有
libssl-dev（Debian）或openssl（macOS via Homebrew） - 国内访问 GitHub 或 php.net 源慢：可设置镜像环境变量，例如
export PHP_BUILD_MIRROR=https://phpenv.php.net/mirrors - 未启用
php-build插件：phpenv 默认不带安装能力，必须手动克隆插件：git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
local / global / shell 切换行为差异
三种命令影响范围不同，且优先级为 local > shell > global。容易混淆的是 local 实际写入的是当前目录下的 .php-version 文件，不是“只对当前终端生效”：
-
phpenv local 7.4.33→ 在当前目录生成.php-version，内容就是7.4.33；cd 进该目录后，任何新打开的终端都会读取它 -
phpenv global 8.3.13→ 写入~/.phpenv/version，作为兜底版本；当找不到.php-version且没设shell时才生效 -
phpenv shell 5.6.40→ 仅在当前 shell 生命周期内生效，关闭终端即失效；适合临时验证某段脚本兼容性
执行后务必运行 phpenv rehash，否则 php 命令仍可能指向旧版本的 shim。
立即学习“PHP免费学习笔记（深入）”；
php 命令没变？检查 shim 是否生效
phpenv 不直接替换系统 PHP，而是靠 shims 目录下的代理脚本拦截调用。如果 php -v 仍显示系统自带版本，大概率是 shim 机制没启动：
- 确认
$HOME/.phpenv/shims已加入PATH，且位置比系统/usr/bin等更靠前（可用echo $PATH查看） - 确认
eval "$(phpenv init -)"已正确写入 shell 配置（~/.bashrc或~/.zshrc），并执行过source ~/.zshrc - 检查
which php输出是否为$HOME/.phpenv/shims/php；如果不是，说明 PATH 或 init 未生效 - 某些 IDE（如 VS Code 终端）会复用旧 shell 环境，重启 IDE 或终端窗口常能解决
最常被忽略的一点：phpenv 安装的每个 PHP 版本默认不含所有扩展（比如 pdo_mysql、opcache），需要手动启用配置文件里的对应行，或重装时加 --enable-opcache 参数。别假设“装完就能跑 Laravel”。
