phpenv本身不安装PHP版本，需先手动安装php-build插件并解决系统编译依赖，再通过phpenv install命令精确安装指定版本（如8.3.13），各版本独立存放于~/.phpenv/versions/下；切换依赖global、local、shell三级作用域机制，优先级为shell＞local＞global，且必须执行phpenv rehash并确保PATH包含~/.phpenv/shims才能生效。
phpenv 本身不直接“配置多个PHP版本”，它只负责管理已安装的版本并切换生效路径。真正要跑多个版本，得先装上它们——而默认安装过程不会自动帮你装任何PHP，必须手动触发 phpenv install。
安装前必须装好 php-build 插件
没有 php-build，phpenv install 命令根本不存在，会报错 phpenv: no such command 'install'。
插件不是内置的，得自己克隆进去：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
装完后还得确保系统有编译依赖，否则安装 PHP 时大概率失败：
立即学习“PHP免费学习笔记（深入）”；
- Ubuntu/Debian：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev - macOS（Homebrew）：
brew install autoconf automake openssl@3 readline zlib
漏掉任何一个关键依赖，phpenv install 8.3.13 就会在 configure 或 make 阶段卡住，错误信息里常带 configure: error: cannot find ssl.h 或 readline/readline.h: No such file or directory 这类提示。
安装多个版本的实际命令和路径差异
phpenv install 默认把每个版本装到 $(phpenv root)/versions/ 下独立子目录，比如 ~/.phpenv/versions/7.4.33 和 ~/.phpenv/versions/8.3.13。这些路径互不干扰，但要注意：
- 版本号必须精确匹配官方发布名，
phpenv install 8.3会失败，得写全8.3.13（查可用列表用phpenv install --list） - 安装过程耗时较长（5–20 分钟），期间不要中断终端；失败后重试前建议先
rm -rf ~/.phpenv/versions/8.3.13清残留 - 装完必须执行
phpenv rehash，否则php命令仍指向旧版本或报command not found
验证是否真装上了：phpenv versions 应显示带星号的当前版本，以及所有已安装项，例如：
* 8.3.13 7.4.33
切换时三种作用域的真实行为区别
phpenv global、phpenv local、phpenv shell 不是简单改个变量，而是通过写不同位置的标记文件来控制 shims 的解析逻辑：
-
phpenv global 8.3.13→ 写入~/.phpenv/version，影响所有未被局部覆盖的目录 -
phpenv local 7.4.33→ 在当前目录生成.php-version文件，内容就一行7.4.33，进入该目录自动生效 -
phpenv shell 5.6.40→ 设置临时环境变量PHPENV_VERSION=5.6.40，仅当前终端有效，关掉就消失
优先级顺序是：shell > local > global。容易踩的坑是：phpenv local 后忘了进对目录，或者 .php-version 文件被 Git 忽略导致协作时别人切不到正确版本。
为什么 php -v 没变？检查这三处
切换后 php -v 仍显示老版本，90% 是因为 which php 返回的不是 ~/.phpenv/shims/php：
- 检查
echo $PATH开头是否有~/.phpenv/shims，且位置比/usr/bin或/opt/homebrew/bin更靠前 - 确认没在别处（如
/etc/profile或~/.zprofile）重复定义了PATH覆盖了 shims 路径 - 运行
phpenv which php，它应输出类似~/.phpenv/versions/8.3.13/bin/php；如果报错或路径不对，说明 shims 没生效
最隐蔽的问题是：某些 IDE（如 VS Code 终端）启动时没加载你的 .bashrc 或 .zshrc，导致 phpenv init 没执行，shims 根本没注册——这时得在 IDE 设置里指定登录 shell 启动方式。
实际用起来，.php-version 文件比 phpenv local 命令更可靠；而 phpenv shell 适合快速验证某个脚本在旧版 PHP 下是否崩溃，不用污染项目配置。
