phpenv是专为Linux/macOS/WSL设计的命令行PHP多版本管理工具，非Windows图形版PHPEnv；需git clone安装，依赖shims机制实现版本切换，不支持.php-version则无法自动识别项目版本。
phpEnv 不是官方 PHP 官方维护的工具，也不是 Windows 上那个带 Apache/MySQL 的“PHPEnv”图形安装包——你真正需要的是 phpenv（纯命令行、类 rbenv 的 Shell 工具），否则后续所有版本切换、.php-version 自动识别、phpenv install 编译安装都会失败。
确认你装的是 phpenv 而不是 phpEnv（Windows 图形版）
很多用户卡在第一步：搜“phpEnv 下载”，点进官网或百度结果，下的是 Windows 下带控制面板的 PHPEnv.exe。这个工具和 phpenv 完全无关，不支持 phpenv install、没有 shims 机制、也不能通过 .php-version 切换项目级版本。
- 如果你用的是 Linux/macOS 或 WSL，必须用
git clone安装phpenv：git clone https://gitcode.com/gh_mirrors/ph/phpenv ~/.phpenv - Windows 原生用户若坚持用图形版 PHPEnv，请放弃多版本管理需求——它只预装一个 PHP，且无法动态切换；真要多版本，得换
phpenv+ WSL2 或直接用 Docker - 执行
which phpenv，输出应为/home/xxx/.phpenv/bin/phpenv（Linux/macOS）或类似路径；若指向C:\PHPEnv\下某个 exe，则不是你要的工具
安装后 php -v 不变？检查 PATH 和 shim 是否生效
常见现象：执行 phpenv global 8.3.13 后，php -v 仍显示系统自带 PHP（如 Ubuntu 的 8.1）。这不是安装失败，而是 phpenv 的 shim 没接管命令调用链。
- 确认
~/.phpenv/shims在$PATH最前面：echo $PATH | grep shims应返回含shims的路径 - 检查
eval "$(phpenv init -)"是否已写入 shell 配置文件（~/.bashrc或~/.zshrc），且已执行source ~/.bashrc - 运行
phpenv rehash—— 这步必须做，否则新安装的 PHP 版本不会生成对应 shim 文件，php命令根本不会被重定向 - 验证是否生效：
which php应输出~/.phpenv/shims/php，而非/usr/bin/php
phpenv install 编译慢 / 失败？提前装依赖并跳过测试
phpenv install 实际调用 php-build 插件编译源码，耗时长、易因缺依赖中断。Ubuntu/Debian 系统典型缺失项包括：autoconf、bison、libxml2-dev、libssl-dev、libcurl4-openssl-dev、libreadline-dev、zlib1g-dev。
立即学习“PHP免费学习笔记（深入）”；
- 一次性装全（Ubuntu/Debian）：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev libxml2-dev - 跳过耗时的
make test（默认开启）：PHP_BUILD_SKIP_TEST=1 phpenv install 8.3.13 - 指定本地镜像加速下载源码包（国内用户必备）：
PHP_BUILD_MIRROR=https://mirrors.huaweicloud.com/php phpenv install 8.3.13 - 编译过程卡在 configure 阶段？大概率是 OpenSSL 版本不兼容，加环境变量强制指定：
PHP_BUILD_CONFIGURE_OPTS="--with-openssl=/usr/lib/ssl" phpenv install 8.3.13
性能关键：别让 phpenv 拖慢每次 shell 启动
eval "$(phpenv init -)" 会在每个新 shell 中执行，如果 ~/.phpenv/versions/ 下装了 10+ 个 PHP 版本，初始化可能延迟 300–500ms。这不是 bug，是设计使然——它要扫描所有版本、生成 shim、加载插件。
- 日常开发中，**90% 场景只需 2–3 个稳定版本**（如 7.4.33、8.1.27、8.3.13），删掉不用的：
rm -rf ~/.phpenv/versions/5.6.40 - 避免在
~/.bashrc里重复eval "$(phpenv init -)"—— 多次执行会叠加初始化开销 - 如完全不需要自动版本切换（比如只用全局版本），可改用轻量初始化：
eval "$(phpenv init --no-shim) "，但会失去.php-version支持 - 终端启动慢？用
time bash -i -c "exit"测初始化耗时，确认瓶颈是否来自 phpenv
最常被忽略的一点：phpenv 本身不提供 PHP 扩展（如 Xdebug、opcache 配置），所有扩展开关、内存限制、错误报告等级，都得去对应版本的 ~/.phpenv/versions/8.3.13/etc/php.ini 里手动改——phpenv 只管“哪个 php 二进制被调用”，不管“这个 php 怎么跑”。
