phpenv是Linux/macOS下命令行PHP版本管理工具，需git克隆、配置shell环境并安装php-build插件才能使用install等命令；PHPEnv则是Windows图形化集成包，二者不可混淆。
phpenv 不是双击安装的图形化工具，也不是 Windows 下的 PHPEnv（带 GUI 的集成包）。如果你搜的是“phpEnv下载配置”，但实际想管理多版本 PHP，**请立刻分清这两个工具**：前者是 Linux/macOS 下命令行驱动的版本管理器（phpenv），后者是 Windows 下打包 Apache+MySQL+PHP 的一键环境（PHPEnv）。装错方向，后面所有操作都会卡死。
确认你用的是 phpenv 还是 PHPEnv
先看命令行能不能打出 phpenv --version。能打出，说明你走的是开源命令行路线；如果双击打开一个带按钮的窗口，那你是 PHPEnv 用户——它不支持 phpenv install 或 phpenv local 这类命令。
常见混淆点：
-
PHPEnv（大写 P、E、N、V）：Windows 软件，官网提供 exe 安装包，无终端命令，靠界面点选 PHP 版本 -
phpenv（全小写）：类 Unix 系统工具，靠 shell 配置 + git 克隆，必须用终端操作 - 搜索“phpenv windows”基本无效——它官方不支持 Windows，强行用 WSL 可以，但别指望 cmd 或 PowerShell 原生跑通
phpenv 安装失败最常见的三个原因
不是网络差，也不是权限不够，而是这三处没对齐：
- Shell 配置文件写错了位置：
~/.bashrc和~/.zshrc不能混用。Zsh 用户改~/.zshrc，Bash 用户改~/.bashrc，改错一个就phpenv命令未找到 -
phpenv init -输出内容没正确 eval：复制粘贴时多了空格或换行，或者用了单引号包裹整个eval "$(phpenv init -)"，导致 shell 没执行初始化 - 没装
php-build插件却直接运行phpenv install 8.3.13：这个命令本身不带编译能力，必须先git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
phpenv 版本切换为什么有时不生效
你以为 phpenv local 7.4.33 写进项目目录了，php -v 却还是 8.3？大概率是下面某一条在作怪：
立即学习“PHP免费学习笔记（深入）”；
-
.php-version文件被 Git 忽略或没提交：该文件必须存在且内容只有7.4.33（前后不能有空格、空行） - 当前目录下有
.phpenv/versions/7.4.33，但没运行过phpenv rehash：shim 文件没更新，php命令仍指向旧版本 - 你用
phpenv shell 8.0.1设置过会话级版本，它优先级高于local，得先执行phpenv shell --unset才能回落到项目设置 - IDE（如 VS Code）开了独立终端或没重载 shell 配置：关掉终端再开，或手动
source ~/.zshrc
PHPEnv（Windows 图形版）启动 Apache 失败怎么查
红色按钮点不动，日志里只有一句 Apache start failed，别急着重装。先做这三件事：
- 点控制面板右上角「配置」→「端口检测」：80 端口被 Skype、IIS、甚至某些国产软件占了很常见，改成 8080 后重启试试
- 检查安装路径：含中文、空格、或在
C:\Program Files下会导致 Apache 加载模块失败，建议装到D:\phpenv-win\这类纯英文无空格路径 - 杀毒软件拦截：360、火绒常把
httpd.exe当可疑进程干掉，临时禁用再启动一次，成功后再加白名单
phpenv 的核心逻辑是“路径劫持”——它不改系统 PHP，只是在你敲 php 时，悄悄把你导到某个版本的 shim 可执行文件。这意味着任何绕过 shim（比如直接调用 /usr/bin/php）的操作，都会脱离版本控制。这点容易被忽略，尤其在写 CI 脚本或 Dockerfile 时。 
