phpenv是基于Shell脚本和插件架构的PHP版本管理工具，需通过git和curl安装，推荐使用phpenv-installer一键部署并自动配置PATH、init及php-build插件，安装后须执行phpenv rehash更新shims，项目版本由根目录的无BOM、无空格的.php-version文件指定。
phpenv 不是“下载安装包”式的传统软件，它没有预编译二进制、不提供 .exe 或 .dmg，本质是一个 Shell 脚本集合 + 插件架构的版本管理工具。直接去官网或镜像站找“安装包”会走弯路。
安装前必须确认：你有没有 git 和 curl
这两个命令是基础依赖，缺一不可：git 用于克隆源码，curl 用于后续安装 PHP 版本时拉取源码包。
运行 git --version 和 curl --version 验证。若报 command not found，请先装好再继续。
推荐用 phpenv-installer 一键安装（最稳）
手动 clone + 配置容易漏掉 php-build 插件，而 phpenv-installer 默认集成它，省去后续补救步骤。
执行以下命令（无需 sudo）：
curl -L https://raw.githubusercontent.com/phpenv/phpenv-installer/master/bin/phpenv-installer | bash
它会自动完成三件事：
- 把 phpenv 克隆到 $HOME/.phpenv
- 添加 PATH 和 eval "$(phpenv init -)" 到 ~/.bash_profile（macOS）或 ~/.bashrc（Linux）
- 克隆 php-build 插件到 $(phpenv root)/plugins/php-build
立即学习“PHP免费学习笔记（深入）”；
安装完立即生效，不用 exec $SHELL -l —— 安装器已帮你 reload。
phpenv install 失败常见原因和绕过方法
运行 phpenv install 8.3.13 卡住或报错，90% 是网络或依赖问题，不是 phpenv 本身故障：
- 国内访问 github.com 慢 → 改用镜像源：在执行前加环境变量
PHP_BUILD_MIRROR=https://mirrors.huaweicloud.com/php - 缺少编译依赖 → Ubuntu/Debian 执行
sudo apt install build-essential libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev autoconf bison re2c pkg-config；macOS 用brew install autoconf bison re2c pkg-config openssl@3 libxml2 libpng libjpeg-turbo - 安装后
php -v仍显示旧版本 → 忘了运行phpenv rehash。每次install或uninstall后都必须执行它，否则 shims 不更新
.php-version 文件必须放在项目根目录，且不能有空格或 BOM
这是 phpenv 自动识别项目 PHP 版本的唯一依据。常见翻车点：
- 文件名写成
.php_version或php-version→ 必须是.php-version - 用 Windows 记事本保存 → 带 UTF-8 BOM，导致
phpenv local解析失败。用 VS Code、Sublime 或echo "8.3.13" > .php-version直接生成最安全 - 文件内容末尾多了一行空行 → 有些老版本
php-build会把换行符当版本号的一部分，报 “no such version” - 路径里有中文或空格 →
phpenv在某些 shell 下解析异常，建议开发路径全英文、无空格
真正麻烦的从来不是装不上，而是装上了却切不到预期版本——那大概率是 .php-version 文件位置或格式不对，或者忘了 rehash。
