phpenv能实现一键切换，但需安装路径、shell配置和php-build插件三者齐全；缺一则phpenv global/local会静默失效，常见问题源于环境变量未正确加载或插件缺失。
phpenv 能实现真正的“一键切换”，但前提是安装路径、shell 配置、插件三者全部到位；缺一不可，否则 phpenv global 或 phpenv local 会静默失效。
安装失败最常卡在环境变量配置这一步
很多人执行完 git clone 就以为装好了，结果 phpenv --version 报 command not found。根本原因是 shell 没加载到 phpenv 的 bin 目录和 shim 初始化逻辑。
- 必须把这两行同时写入你的 shell 配置文件（
~/.bashrc或~/.zshrc）：export PATH="$HOME/.phpenv/bin:$PATH"eval "$(phpenv init -)" - 写完不能只改文件就完事——要执行
source ~/.bashrc（或source ~/.zshrc），或者新开终端；用exec $SHELL -l也行，但不如source直观可控 - 验证是否生效：运行
which phpenv应该返回类似/home/xxx/.phpenv/bin/phpenv；运行phpenv --version有输出才算成功
没有 php-build 插件，phpenv install 命令根本不能用
phpenv 本身不带编译能力，它只是个版本路由层。所有 phpenv install xxx 的实际工作都由 php-build 插件完成。跳过这步，你连第一个 PHP 版本都装不上。
- 手动安装插件命令（必须在
phpenv初始化之后执行）：git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 安装前建议先装系统依赖，否则编译大概率失败：
sudo apt install build-essential libssl-dev libxml2-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev autoconf（Ubuntu/Debian） - 装完插件再试：
phpenv install 8.3.13；若提示 “command not found: phpenv-install”，说明插件没放对位置或没 reload shell
phpenv local 不生效？检查 .php-version 文件和目录层级
这个命令本质是往当前目录写一个 .php-version 文件，然后靠 shims 在执行 php 时自动读取。常见失效原因不是命令错了，而是路径或权限问题。
立即学习“PHP免费学习笔记（深入）”；
-
phpenv local 7.4.33必须在项目根目录下运行，且该目录需有写权限；它生成的.php-version是纯文本，内容就是7.4.33（无空格、无换行） - 进入目录后，用
phpenv version查看当前解析来源；如果显示system，说明没读到.php-version，可能因为：
— 当前目录上层某处也有.php-version（优先级更高）
— 文件编码是 Windows-style CRLF（某些 shell 解析失败）
— 目录名含空格或特殊字符（极少见但存在） - 临时调试可用：
phpenv which php看当前php二进制路径是否指向~/.phpenv/versions/7.4.33/bin/php
全局 vs 本地 vs shell 会话：三者冲突时谁赢？
phpenv 按照固定顺序决定最终用哪个版本：shell 会话 > 本地（.php-version） > 全局（~/.phpenv/version）。这个优先级不能改，但容易被忽略。
-
phpenv shell 5.6.40只影响当前终端，关掉就消失；适合快速验证旧版兼容性 -
phpenv global 8.3.13写入~/.phpenv/version，对所有没设 local 或 shell 的场景生效 - 一旦设置了
phpenv shell，即使你 cd 进某个.php-version为 7.4.33 的项目，php -v仍显示 5.6.40——这是设计行为，不是 bug - 清除 shell 级别设置：运行
phpenv shell --unset；清除 local 设置：删掉项目下的.php-version
真正麻烦的从来不是“怎么切”，而是“为什么没切”——绝大多数问题出在 shim 机制没激活、插件缺失、或路径优先级被意外覆盖。动手前先跑一遍 phpenv version 和 phpenv which php，比盲目重装快得多。
