phpenv 是一个专为 macOS 和 Linux 设计的轻量级命令行工具，通过拦截 (shim) 机制让你能在同一台机器上轻松安装和切换多个 PHP 版本。
它与 Windows 下带图形界面的 phpEnv 是两套完全不同的东西，使用时请注意区分。
⚙️ 安装与配置
phpenv 本身并不提供 PHP，你需要配合 php-build 插件来编译安装具体版本，它的安装通常是这样的：
1. 克隆 phpenv 仓库
git clone https://github.com/phpenv/phpenv.git ~/.phpenv
2. 配置环境变量
根据你使用的 Shell (如 ~/.bashrc, ~/.zshrc)，添加以下内容：
export PATH="$HOME/.phpenv/bin:$PATH"
eval "$(phpenv init -)"
3. 重新加载配置
exec $SHELL -l
4. 安装 php-build 插件
git clone https://github.com/php-build/php-build.git $(phpenv root)/plugins/php-build
5. 安装具体的 PHP 版本
例如安装 PHP 8.2.12：
phpenv install 8.2.12
6. 生成 shim 文件
这一步非常关键， 它能确保 php 等命令通过 phpenv 的 shim 层被正确转发。
phpenv rehash
7. 验证安装
phpenv --version
php --version
📝 常用命令速查
phpenv versions：列出所有已安装的 PHP 版本。phpenv version：显示当前使用的 PHP 版本。phpenv global <版本号>：设置全局默认版本。phpenv local <版本号>：为当前项目目录设置特定版本。phpenv shell <版本号>：仅为当前 Shell 会话设置版本。phpenv rehash：安装新版本后重新生成 shim 文件。phpenv which php：显示当前php命令的实际路径。
⚠️ 常见问题与解决
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
phpenv: command not found | phpenv 路径未添加到 PATH 环境变量中。 | 检查并重新配置环境变量，然后重启终端或执行 source ~/.bashrc 等命令。 |
phpenv install 时报错 | 缺少编译 PHP 所需的系统依赖包，如 libxml2-dev、libssl-dev 等。 | 安装系统依赖，例如 Ubuntu/Debian：sudo apt-get install build-essential libxml2-dev libssl-dev。 |
php -v 显示的版本和设置的不一致 | 安装新版本后未执行 phpenv rehash，导致 shim 文件未更新。 | 运行 phpenv rehash。 |
项目中已设置 .php-version 但未生效 | 当前终端会话未正确初始化 phpenv。 | 确保在 Shell 配置文件中正确添加了 eval "$(phpenv init -)"，或重启终端。 |
在 Windows 上无法使用 phpenv 命令 | 下载了错误的工具，phpenv 不支持原生 Windows 系统。 | 在 Windows 上应使用 WSL2 或在命令行中考虑 PVM for Windows 等工具。 |