phpenv是纯命令行工具，无图形界面，通过终端管理PHP版本；安装需克隆仓库、配置PATH、执行eval "$(phpenv init -)"并rehash，.php-version文件实现项目级版本隔离。
phpenv 没有图形界面，它是一个纯命令行工具。所有操作都通过终端完成，不存在“多版本管理界面”这种说法——如果你看到带 UI 的 PHP 版本管理器，那大概率是别的工具（比如 brew + 自定义脚本、或某些 IDE 插件），不是 phpenv 本身。
下面直接说清楚怎么装、怎么用、哪些地方容易卡住。
安装失败最常见的三个原因
你执行 phpenv --version 报错或提示 command not found，基本逃不出这三种情况：
-
~/.phpenv/bin没进PATH：检查echo $PATH输出里有没有这一段； - 没运行
eval "$(phpenv init -)"：这个命令生成的 shim 是切换版本的核心，漏掉就完全不生效； - 改了错误的 shell 配置文件：比如用
zsh却只改了~/.bashrc，应该改~/.zshrc。
安装流程必须按顺序走这四步
跳过任意一步都可能让后续命令失效：
- 克隆仓库到固定路径：
git clone https://gitcode.com/gh_mirrors/ph/phpenv ~/.phpenv（注意是~/.phpenv，不是/usr/local/phpenv或其他）； - 写入环境变量（以
zsh为例）：echo 'export PATH="$HOME/.phpenv/bin:$PATH"' >> ~/.zshrc； - 启用 shim 和自动补全：
echo 'eval "$(phpenv init -)"' >> ~/.zshrc； - 重载配置：
source ~/.zshrc（别用exec $SHELL -l，它会清空当前会话变量）。
安装完 PHP 版本后必须运行 phpenv rehash
这是最容易被忽略的一步。你执行 phpenv install 8.3.13 成功后，php 命令仍可能指向系统旧版本，因为 phpenv 的 shim 机制需要手动刷新映射表：
立即学习“PHP免费学习笔记（深入）”；
- 每次新装一个 PHP 版本，都要立刻跑一次
phpenv rehash； - 如果装完版本后
php -v不变，先确认which php是否指向~/.phpenv/shims/php； - 如果不是，说明
rehash没成功，或者有其他 PHP 路径（如/usr/bin/php）在PATH中排得更前。
.php-version 文件不是可选功能，而是项目隔离的关键
很多人以为 phpenv local 8.3.13 就够了，其实它只是在当前目录下生成一个 .php-version 文件。真正起作用的是这个文件本身和 phpenv 的自动检测逻辑：
- 文件内容只能是一行纯版本号，比如
8.3.13，不能带空格、注释或引号； - 进入目录时，
phpenv会从当前路径逐级向上找.php-version，找到第一个就用它； - 如果父目录也有该文件，子目录没覆盖，就会继承上级版本——这点常导致“为什么换目录 PHP 版本没变”。
复杂点在于：shim 机制依赖 shell 初始化顺序，PATH 冲突比想象中更顽固；.php-version 的层级查找逻辑也容易误判。动手前先 which php 看路径，比盲目重装管用得多。
