phpenv是Shell层PHP版本路由工具，需Git克隆+PATH配置+eval "$(phpenv init -)"双配置生效，缺一不可；依赖php-build插件及编译工具链，版本切换依shell>local>global优先级，且必须rehash更新shim。
phpenv 不是 Windows 上双击安装的图形工具，也不是开箱即用的“集成环境”。它本质是一个 Shell 层的 PHP 版本路由工具，依赖你本地已有的编译链和基础工具链。直接下载 zip 包或双击运行无法生效——必须通过 Git 克隆 + Shell 配置才能启动。
克隆仓库后 PATH 和 init 必须同时生效
只执行 git clone https://gitcode.com/gh_mirrors/ph/phpenv ~/.phpenv 是不够的。两个配置缺一不可：
-
export PATH="$HOME/.phpenv/bin:$PATH"让系统能识别phpenv命令 -
eval "$(phpenv init -)"启用 shim 机制，把php、phpize等命令重定向到当前激活版本
很多人卡在 phpenv: command not found，就是只加了 PATH 没跑 init；或者反过来，init 了但 PATH 没导出，导致 phpenv 命令本身都找不到。
注意：Bash 用户写入 ~/.bash_profile 或 ~/.bashrc；Zsh 用户必须写入 ~/.zshrc，否则 source ~/.zshrc 不会加载错文件。
install 命令依赖 php-build 插件，不装就报错
phpenv install 8.3.13 默认不会工作——它背后调用的是 php-build，而这个插件不是 phpenv 自带的。
立即学习“PHP免费学习笔记（深入）”；
- 必须手动安装：
git clone https://gitcode.com/gh_mirrors/ph/php-build $(phpenv root)/plugins/php-build - 安装前确保系统有
autoconf、openssl、libxml2-dev（Ubuntu/Debian）或libxml2-devel（CentOS/RHEL）等编译依赖 - macOS 用户需先装 Xcode Command Line Tools：
xcode-select --install
常见错误：phpenv: install: command not found 或 php-build: command not found，基本都是插件没装或依赖缺失。
local / global / shell 切换逻辑容易混淆
phpenv 的版本优先级是：shell > local > global。但实际行为取决于当前目录是否存在 .php-version 文件：
-
phpenv local 7.4.33→ 在当前目录生成.php-version，内容为7.4.33 -
phpenv global 8.3.13→ 写入~/.phpenv/version，作为兜底 fallback -
phpenv shell 8.2.0→ 仅当前终端生效，关闭即失效，不写任何文件
陷阱：如果你在项目根目录执行了 phpenv local 7.4.33，然后 cd 进子目录再运行 php -v，依然会读取父目录的 .php-version —— 它是向上递归查找的，不是仅限当前目录。
rehash 不是可选项，而是高频刚需
每次 phpenv install 成功后，或手动删改过 ~/.phpenv/versions/ 下的版本目录，都必须立刻执行：
phpenv rehash
否则 php、phpize、pear 等二进制 shim 文件不会更新，你会遇到：
-
php: command not found（即使phpenv versions显示已安装） -
phpenv which php返回空或错误路径
这不是 bug，是 phpenv 的设计机制：shim 是静态生成的，不监听文件系统变化。
phpenv 的核心复杂点不在安装步骤本身，而在于它把“PHP 版本选择”从编译时移到了运行时，并靠 Shell 层的路径劫持实现。这意味着每一步配置都必须精准落在 Shell 初始化链上，漏掉一个 source、写错一个配置文件路径、忘记 rehash，都会让整个链条断掉。它不报错，只是静默失效。 
