phpenv本身不安装PHP，仅通过shim动态路由；必须先安装php-build插件才能使用phpenv install命令，否则报“no such command”。
直接说结论：phpenv 不是“配置多版本 PHP”，而是通过 shim 机制在运行时动态路由到对应版本的 php 二进制，真正的多版本安装依赖插件 php-build；没装它，phpenv install 命令根本不存在。
phpenv install 命令报错：command not found
这是最常卡住的第一步。phpenv 本体只管切换和路由，不负责编译安装 —— 它把这事交给 php-build 插件。如果你刚克隆完 phpenv 就跑 phpenv install 8.3.13，一定会失败。
- 必须先手动安装插件：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 确认插件目录存在：
ls $(phpenv root)/plugins/应该能看到php-build - 部分旧文档用的是镜像地址（如
gitcode.com/gh_mirrors/ph/php-build），但主仓库已迁回 GitHub，优先用官方源 - 装完插件后，
phpenv install --list才能列出可安装版本；否则提示no such command
安装 PHP 版本时编译失败
报错通常以 configure: error: 或 make: *** No rule to make target 开头，本质是系统缺编译依赖，不是 phpenv 的问题。
- Ubuntu/Debian 系统必备：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev - macOS（Homebrew）：
brew install autoconf automake openssl@3 libxml2 libxslt，注意 PHP 8.3+ 默认要求 OpenSSL 3 -
php-build默认不启用 PEAR/PECL，如需pecl命令，得提前设环境变量：export PHP_BUILD_CONFIGURE_OPTS="--with-pear" - 安装中途中断后，再运行
phpenv install会复用缓存源码但不清残留对象，建议删掉$(phpenv root)/versions/8.3.13和~/.php-build/cache/php-8.3.13.tar.xz重试
切换了版本，php -v 还是旧版本
说明 php 命令没走 phpenv 的 shim，而是调用了系统 PATH 中更靠前的其他 PHP（比如 apt/yum 装的、MAMP 自带的、或 Homebrew 的 /opt/homebrew/bin/php）。
立即学习“PHP免费学习笔记（深入）”；
- 查真实执行路径：
which php，输出不该是/usr/bin/php或/opt/homebrew/bin/php，而应是~/.phpenv/shims/php - 检查
~/.phpenv/shims是否在$PATH最前面：echo $PATH | tr ':' '\n' | head -5 - 如果
~/.phpenv/shims在~/.phpenv/bin后面，说明你漏了eval "$(phpenv init -)"—— 它不只是加自动补全，核心是把 shims 目录 prepended 到 PATH - 改完配置记得
source ~/.bashrc（或对应 shell 文件），别只exec $SHELL -l，后者可能不读取新配置
项目级版本不生效：.php-version 文件被忽略
phpenv 只在当前目录或父级目录找到 .php-version 时才触发本地版本，且文件内容必须**纯版本号**，不能带空格、注释或额外字符。
- 正确写法：
echo "7.4.33" > .php-version，然后cd .. && cd -触发重载 - 错误写法：
echo "# PHP 7.4" > .php-version或echo "7.4.33 " >> .php-version（末尾空格）都会导致 fallback 到全局版本 - 调试用：
phpenv version显示当前生效版本及来源（如7.4.33 (set by /path/to/project/.php-version)） - 注意：.php-version 对子目录递归生效，但若子目录里有另一个
.php-version，则以最近的为准
真正容易被忽略的点是：phpenv 的 shim 是 bash/zsh 函数劫持 + 文件代理的混合机制，它不修改 php 本身，只控制调用链起点。一旦 PATH 或 shell 初始化出偏差，整个链条就断了 —— 所以别跳过 which php 和 phpenv version 这两个验证动作。
