phpenv 是 Shell 级命令行工具，非图形化，必须配置 PATH 和执行 eval "$(phpenv init -)" 才可用；提示 “command not found” 仅因路径未添加或 shims 未激活。
直接说结论：phpenv 不是开箱即用的图形化工具，它本质是一个 Shell 级的 PHP 版本管理器，必须在终端里操作，且依赖系统基础编译环境。装完不配置 PATH 和 eval "$(phpenv init -)"，phpenv 命令根本不会被识别——这不是 bug，是设计使然。
为什么 phpenv 命令提示 “command not found”
这是新手最常卡住的第一步。根本原因只有两个：
-
~/.phpenv/bin没加进PATH，Shell 找不到可执行文件 -
eval "$(phpenv init -)"没执行，shims 机制没激活，php命令仍指向系统自带或别的 PHP
检查方法很简单：echo $PATH 看输出里有没有 ~/.phpenv/bin；再运行 which php，如果返回的是 /usr/bin/php 或 /opt/homebrew/bin/php，说明 phpenv 还没接管命令。
phpenv install 失败：缺依赖、权限、或网络问题
安装 PHP 源码版本（比如 phpenv install 8.3.13）不是下载一个二进制就完事。它实际是在本地编译，所以失败几乎都源于环境缺失：
立即学习“PHP免费学习笔记（深入）”；
- Ubuntu/Debian：缺
autoconf、libssl-dev、zlib1g-dev等，用sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev补齐 - macOS：Homebrew 没装
openssl或zlib，先brew install openssl zlib，再导出环境变量：export PHP_BUILD_CONFIGURE_OPTS="--with-openssl=/opt/homebrew/opt/openssl --with-zlib-dir=/opt/homebrew/opt/zlib" - Windows 用户注意：
phpenv官方不支持 Windows，所谓“PHPEnv”图形工具（如 phpenv.cn 那个）和phpenv是两回事，别混用
怎么让项目自动用对 PHP 版本
靠的是层级优先级 + 文件触发，不是全局设置一劳永逸：
- 项目根目录放一个
.php-version文件，内容就一行：8.3.13（不能带空格或注释） - 进到该目录后，
php -v就会显示 8.3.13；cd出去就恢复上层设置 - 优先级顺序是：
phpenv shell < phpenv local < phpenv global，其中shell级别只在当前终端生效，关掉就失效 - 改完
.php-version或切换global后，记得手动运行phpenv rehash，否则新版本的 bin 文件不会被 shims 自动映射
phpenv 和图形化 “PHPEnv” 工具完全无关
这点极其容易混淆。搜索“phpenv 教程”出来的很多中文页面，讲的是 Windows 上那个带 Apache/MySQL 图形界面的 PHPEnv（官网 phpenv.cn），而 GitHub 上的 phpenv（php-build/phpenv）是纯命令行、仅管理 PHP 解释器的工具。两者同名不同物，代码库、维护者、适用平台、使用方式全都不一样。如果你在 Windows 上双击安装了一个.exe，那你就没在用这个 phpenv，也别照着 Linux/macOS 的教程敲命令。
