phpenv必须通过git clone源码安装并配置Shell环境才能正常使用；混用官网“一键版”会导致命令冲突；需正确设置PATH、执行phpenv init、安装php-build插件，并在项目根目录使用phpenv local。
phpenv 不是官网下载的安装包，不能双击运行；它必须通过 Git 克隆 + Shell 配置才能生效。直接去 phpenv.cn 下载的“Windows 一键版”和真正的 phpenv 是两套东西，混用会导致命令冲突、版本不一致、phpenv local 失效。
git clone 是唯一可靠安装方式
所有稳定、可维护的 phpenv 使用都基于源码克隆。所谓“简易”，是指步骤少，不是指跳过 Shell 配置。
- 运行
git clone https://gitcode.com/gh_mirrors/ph/phpenv ~/.phpenv（注意路径是~/.phpenv，不是任意目录） - 必须把
$HOME/.phpenv/bin加进PATH，否则phpenv命令根本找不到 -
eval "$(phpenv init -)"这一行不能省——它激活 shims 机制，让php命令能被自动路由到当前版本 - 改完配置后必须执行
exec $SHELL -l或source ~/.bashrc，否则新配置不加载
phpenv install 前必须装 php-build 插件
刚装好的 phpenv 默认不带编译能力，phpenv install 8.3.13 会报错：command not found: phpenv-install。
- 手动安装插件：
git clone https://gitcode.com/gh_mirrors/ph/php-build $(phpenv root)/plugins/php-build - 插件装完后，
phpenv install --list才能列出可用版本 - 首次安装 PHP 时建议加
-v参数观察进度，避免卡在 configure 阶段无响应 - 如果提示缺少依赖（如
libxml2-dev、openssl-dev），得先用系统包管理器装好，Ubuntu/Debian 用apt install，macOS 用brew install
local / global / shell 切换行为差异大
三种作用域的优先级是：shell > local > global。但很多人误以为 phpenv local 写入的是项目根目录的 .php-version 文件，其实它写的是当前目录下的 .php-version ——如果你在子目录里执行，就会生成在子目录，导致切换失效。
立即学习“PHP免费学习笔记（深入）”；
- 务必在项目**根目录**执行
phpenv local 8.3.13 - 检查是否生效：运行
phpenv version（输出带空格的两段，如8.3.13 (set by /path/to/project/.php-version)） -
phpenv global改的是~/.phpenv/version文件，影响所有未设 local 的目录 -
phpenv shell是临时的，关掉终端就丢，适合 CI 脚本中快速测试
常见失效场景和快速自检
执行 php -v 还是旧版本？大概率是 shim 没更新或 PATH 错了。
- 先确认
which php输出是不是~/.phpenv/shims/php，不是就说明 shims 未生效 - 运行
phpenv rehash强制重建所有 shim 符号链接 - 检查
~/.phpenv/versions/下对应版本目录是否存在且非空 - 如果
phpenv versions显示为空，说明phpenv install实际没成功，去看编译日志末尾的 error 行
最易被忽略的一点：phpenv 对 shell 类型敏感。用 zsh 却往 ~/.bashrc 写配置，或者用了 oh-my-zsh 但没加载 completions/phpenv.zsh，都会导致 phpenv init 不起作用。别猜，直接查 $SHELL，然后往对应配置文件里加那两行。
