phpenv install 命令报“command not found”是因为缺少 php-build 插件；需手动克隆至 $(phpenv root)/plugins/php-build 目录，并执行 phpenv rehash 更新 shim。
phpenv 本身不自带 PHP 二进制文件，添加新版本必须靠插件 php-build 编译安装——没装这个插件，phpenv install 命令根本不存在。
phpenv install 命令为什么报错“command not found”
这是最常卡住的第一步。phpenv 默认只提供版本切换逻辑，不提供编译能力。所有 phpenv install 相关功能都来自独立插件 php-build，它必须手动安装到指定路径才能被识别。
- 先确认插件是否已存在：
ls $(phpenv root)/plugins/php-build—— 如果提示 “No such file or directory”，说明插件缺失 - 正确安装方式（以 zsh/bash 为例）：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 插件路径不能错：
$(phpenv root)/plugins/是硬编码查找位置，放错目录（比如放在~/plugins/）会导致命令不可用 - 安装后无需重启 shell，但首次运行
phpenv install前建议执行一次phpenv rehash更新 shim
安装 PHP 8.3.13 时 configure 参数不生效
php-build 的编译行为由环境变量 PHP_BUILD_CONFIGURE_OPTS 控制，但它的作用时机很关键：只影响后续的 phpenv install 调用，对已安装版本无效，且不会覆盖默认参数，而是追加。
- 启用 OpenSSL 和 Intl 扩展：
export PHP_BUILD_CONFIGURE_OPTS="--with-openssl --enable-intl" - 如果要替换默认选项（比如禁用 PEAR），得改插件内置配置文件：
~/.phpenv/plugins/php-build/share/php-build/default_configure_options - PHP 8.2+ 默认不再内置 PEAR，若需
pecl，必须显式加--with-pear，否则安装完也找不到pecl命令 - 编译失败常见于缺系统依赖，例如 Ubuntu 需提前装：
sudo apt-get install libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev libicu-dev
本地项目用了 .php-version，但 php -v 还是显示旧版本
这通常不是配置问题，而是 shims 没刷新或 shell 层级覆盖未清除。phpenv 的版本优先级是：shell > local > global，而 php 命令实际调用的是 ~/.phpenv/shims/php，它依赖当前路径和环境变量动态解析。
立即学习“PHP免费学习笔记（深入）”；
- 检查当前目录是否有
.php-version文件，内容只能是纯版本号（如8.3.13），不能带空格或注释 - 运行
phpenv version看输出是否匹配预期——这是唯一可信的当前激活版本指示 - 如果
phpenv version正确但php -v不对，立刻执行phpenv rehash重建所有 shim 符号链接 - 曾用过
phpenv shell 8.1.27的话，该设置会持久影响当前终端，退出前需运行phpenv shell --unset清除
最容易被忽略的是：php-build 插件安装后，phpenv install 下载源码、解压、编译全程无进度提示，耗时可能超过 5 分钟（尤其在 M1 Mac 或低配云服务器上），看起来像卡死；实际只要没报错，就别中断。编译完成前，phpenv versions 不会列出新版本。
