phpenv是Shell脚本工具，所有PHP版本均需源码编译安装，不提供预编译包；常见失败原因包括PATH未正确配置、初始化顺序错误、编译依赖缺失（如libxml2-dev、libonig-dev等）及.php-version文件格式或位置不当。
phpenv 不提供预编译的“组件下载包”，它本身是 Shell 脚本工具，所有 PHP 版本都通过源码编译安装 —— 这意味着你没法像下载 ZIP 那样点几下就装好一个 PHP 二进制，必须本地编译。但好处是：每个版本完全独立、无系统污染、扩展可控。
phpenv 安装失败常见原因和修复
执行 git clone 后 phpenv --version 报 command not found，基本就是 PATH 或初始化没生效：
- 确认克隆路径是
~/.phpenv（不是~/phpenv或其他路径），否则$(phpenv root)会失效 -
export PATH="$HOME/.phpenv/bin:$PATH"必须写入你当前 shell 的配置文件（~/.bashrc或~/.zshrc），而不是~/.bash_profile（macOS Terminal 默认读后者，但 iTerm2 / VS Code 终端常读前者） -
eval "$(phpenv init -)"必须在 PATH 设置之后执行，顺序反了会导致 shim 无法注册 - 执行
source ~/.zshrc（或对应文件）后，再运行which php—— 如果还是指向/usr/bin/php，说明~/.phpenv/shims没进 PATH，phpenv init -输出里应包含这一行，手动加也行
phpenv install 编译失败时该装哪些依赖
phpenv install 本质调用 php-build 插件做 configure + make，缺依赖会直接报错（比如 configure: error: xml2-config not found）。不同系统需提前装好：
- Ubuntu/Debian：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev libxml2-dev libsqlite3-dev libonig-dev - macOS（Homebrew）：
brew install autoconf automake openssl@3 sqlite3 libxml2 oniguruma，并设环境变量：export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"（如需 OpenSSL 支持） - CentOS/RHEL：
sudo yum groupinstall "Development Tools" && sudo yum install -y openssl-devel bzip2-devel curl-devel libxml2-devel sqlite-devel oniguruma-devel - 注意：
libonig-dev（PHP 7.3+ 正则引擎）和libsqlite3-dev（PDO SQLite）容易漏，不装会导致扩展编译跳过或报错
为什么 phpenv local 不生效？.php-version 文件细节
项目级切换靠 .php-version 文件驱动，但它有硬性规则：
立即学习“PHP免费学习笔记（深入）”；
- 文件必须放在项目**根目录**（
pwd输出的路径下），不能在子目录或上层 - 内容只能是纯版本号，例如
8.3.13或7.4.33，不能带空格、注释、前缀（php-8.3.13或# 7.4都无效） - 执行
phpenv local 8.3.13实际就是生成这个文件，但如果你用编辑器保存时用了 BOM 或换行符（比如 Windows 的 CRLF），phpenv会静默忽略 - 验证方式不是只看
php -v，还要运行phpenv version—— 它会明确告诉你当前是local、global还是shell模式，以及对应版本
真正麻烦的是 shims 的透明重定向机制：它靠拦截 php、phpize、pear 等命令，把调用转发到对应版本的 real binary。一旦 which php 还指向系统路径，说明 shim 层根本没加载，这时候翻日志或重跑 phpenv rehash 才是关键，不是反复 phpenv local。
