phpenv必须通过git克隆源码安装，因其核心shim机制依赖~/.phpenv/bin下的脚本，且phpenv install需php-build插件支持，.php-version文件生效需满足路径、命名、内容及shell执行顺序三条件。
phpenv 没有官方二进制下载包，也不提供图形化安装器——它必须通过 Git 克隆源码手动安装，否则后续所有版本管理、phpenv install 等功能都无法使用。
为什么不能用 curl 或 apt 直接装？
因为 phpenv 的核心是 shell shim 机制：它靠在 $PATH 前置一个拦截层，动态替换 php、phpize 等命令的执行路径。这个逻辑完全依赖本地 ~/.phpenv/bin/ 下的脚本，而这些脚本只存在于 Git 仓库中。任何跳过克隆步骤的“一键安装”（比如某些第三方脚本）大概率缺失 phpenv init 所需的 hooks 或插件结构，导致 php -v 不变、phpenv versions 列不出内容。
必须执行的三步初始化（缺一不可）
以下操作针对 Bash/Zsh，路径和配置文件名需按实际 shell 调整：
- 克隆到固定位置：
git clone https://github.com/phpenv/phpenv.git ~/.phpenv - 写入 shell 配置（如
~/.zshrc）：export PATH="$HOME/.phpenv/bin:$PATH"和eval "$(phpenv init -)" - 重载配置：
source ~/.zshrc（不是exec $SHELL -l，后者会丢掉当前环境变量）
验证是否生效：which php 应返回类似 /home/xxx/.phpenv/shims/php；若仍指向 /usr/bin/php，说明 eval "$(phpenv init -)" 没执行成功，常见原因是 shell 配置文件未被正确加载，或 ~/.phpenv 权限异常（如被设为 root 所有）。
phpenv install 报错：command not found？
phpenv install 不是 phpenv 自带命令，它来自独立插件 php-build。没装这个插件，就只能切换版本，不能安装新版本。
立即学习“PHP免费学习笔记（深入）”；
必须手动安装插件：
- 运行：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 确认插件目录存在：
ls $(phpenv root)/plugins/php-build/bin/php-build应输出路径 - 之后才能用：
phpenv install 8.3.13
注意：phpenv install 实际调用的是 php-build 编译流程，因此系统必须预装编译依赖（Ubuntu/Debian 下：sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev），否则会卡在 configure 阶段并报 configure: error: no acceptable C compiler found 类错误。
.php-version 文件不生效？检查这三点
项目级版本控制依赖 .php-version 文件，但它只在满足以下全部条件时才触发：
- 文件必须位于当前工作目录（
pwd输出路径）下，且名为.php-version（不能是php-version或.php_version） - 文件内容只能是纯版本号，如
8.3.13，不能带空格、注释或前缀（php-8.3.13会失败） - 当前 shell 必须已进入该目录后才执行
cd—— 如果你用cd project && php -v写在一行，部分 shell 可能不会触发 shims 重载，建议分两行执行
调试技巧：phpenv version 显示当前生效的版本来源（如 8.3.13 (set by /path/to/project/.php-version)），比 php -v 更直接反映 phpenv 是否接管成功。
