phpenv是Linux/macOS下基于Shell的PHP版本管理工具，与Windows的PHPEnv无关；需配置PATH并执行eval "$(phpenv init -)"才能生效，切换版本后必须运行phpenv rehash。
phpenv 命令行工具：不是 Windows 那个 PHPEnv
先划重点：phpenv（小写 p，无空格）是类 Unix 系统（Linux/macOS）上用 Shell 管理多版本 PHP 的命令行工具，和 Windows 下那个带图形界面、集成 Apache/MySQL 的「PHPEnv」完全无关。两者同名不同物，混用会导致路径错乱、命令找不到、php -v 不变等典型问题。
如果你在 Windows 上搜“phpEnv 下载”，实际该找的是官网打包版安装器（.exe），而不是 git clone；反之，Linux/macOS 用户若去下 .exe 或双击运行，根本跑不起来。
- Linux/macOS 正确入口是 GitHub/GitCode 镜像仓库：
git clone https://gitcode.com/gh_mirrors/ph/phpenv.git ~/.phpenv - Windows 用户请直接访问 PHPEnv 官网下载最新 .exe 安装包，不要尝试用 Git 克隆或执行
phpenv init - Mac 用户注意：M1/M2 芯片需确认已安装 Xcode Command Line Tools（
xcode-select --install），否则phpenv install会卡在 configure 阶段
PATH 和 eval "$(phpenv init -)" 缺一不可
phpenv 启动依赖两个硬性条件：可执行文件在 PATH 中，且 shims 机制被激活。只配 PATH 不跑 eval，phpenv install 能用，但 php 命令仍调用系统默认 PHP；只跑 eval 不配 PATH，则直接报 command not found: phpenv。
- 必须把这两行都加进 shell 配置文件（
~/.bashrc、~/.zshrc或~/.bash_profile）：export PATH="$HOME/.phpenv/bin:$PATH" eval "$(phpenv init -)"
- 改完后别用
exec $SHELL -l—— 这在某些 zsh 版本里会清空已有环境变量；统一用source ~/.zshrc（或对应文件）更稳 - 验证是否生效：
which phpenv应返回~/.phpenv/bin/phpenv；phpenv versions应输出空列表（说明初始化成功，只是还没装版本）
phpenv install 失败的三个高频原因
phpenv install 不是下载即用，它本质是本地编译安装，失败几乎都卡在依赖或权限环节，和网络关系不大。
立即学习“PHP免费学习笔记（深入）”；
- 缺少系统级构建依赖：Ubuntu/Debian 执行
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev；macOS 用brew install autoconf automake openssl@3 pkg-config（注意 OpenSSL 版本要匹配 PHP 源码要求） - 非 root 用户对
/usr/local或/opt无写入权：phpenv默认把编译产物放~/.phpenv/versions/，只要家目录可写就 OK；但若曾手动改过PHPENV_ROOT环境变量，务必检查目标路径权限 - PHP 版本号写错：比如输
phpenv install 8.3会失败（缺补丁号），正确是phpenv install 8.3.13；查可用版本用phpenv install --list | grep "8\.3"
local / global / shell 版本切换的实际效果差异
三种作用域切换不是“谁优先谁覆盖”的简单关系，而是由 ~/.phpenv/version、项目根目录的 .php-version、当前 shell 的 PHPENV_VERSION 环境变量共同决定，且有明确优先级顺序：.php-version > PHPENV_VERSION > ~/.phpenv/version。
-
phpenv global 8.3.13：写入~/.phpenv/version，影响所有未设 local 的目录；但一旦进入含.php-version的项目，自动无视 global -
phpenv local 7.4.33：在当前目录生成.php-version文件，内容就是7.4.33；Git 提交时建议把这个文件加入.gitignore，避免污染团队配置 -
phpenv shell 8.0.1：仅当前终端会话生效，关闭窗口即失效；适合临时调试某段只兼容 PHP 8.0 的扩展代码 - 切完版本后必须执行
phpenv rehash：否则php、composer等 shim 二进制文件不会更新指向，php -v依然显示旧版本
rehash 这一步——它不自动触发，也不在文档显眼位置强调，但没它，所有版本切换都是假动作。 
