Windows用户应下载phpenv.cn的PHPEnv图形化集成环境，Linux/macOS用户须用GitHub镜像源安装phpenv命令行工具；二者名称相似但完全不兼容，混用将导致失效。
Windows 用户直接装官网下载的 PHPEnv（phpenv.cn）即可开箱运行，不用碰命令行；Linux/macOS 用户想管多版本 PHP，必须用 phpenv（GitHub 镜像源），两者不是同一个工具，混用会彻底失效。
区分 phpEnv 和 phpenv：名字像，但完全不兼容
Windows 上流行的「PHPEnv」是图形化集成环境（Apache + MySQL + 多个 PHP 版本打包），安装完点几下就能跑 localhost；而 macOS/Linux 下的 phpenv 是纯命令行版本管理器，只管 PHP 二进制切换，不带 Web 服务。网上很多教程把二者混讲，结果用户在 Windows 下敲 phpenv install 报错，或在 macOS 下双击安装包发现没反应——根源就在这儿。
- 你用的是 Windows？去 phpenv.cn 下载最新
PHPEnv_Setup.exe，别碰 Git 克隆 - 你用的是 macOS 或 Linux？删掉所有 Windows 教程里的双击、桌面快捷方式、端口检测等描述，只认
git clone https://gitcode.com/gh_mirrors/ph/phpenv.git ~/.phpenv - 两者配置文件互不识别：
.php-version在phpenv下生效，在 Windows 的 PHPEnv 里完全被忽略
Windows 用户：跳过所有终端操作，重点看这三处
安装时默认勾选「创建桌面快捷方式」和「开机自启」，但真正影响可用性的只有三个地方：
- 安装路径不能含中文或空格——比如
D:\PHPEnv可以，D:\Program Files\PHPEnv或D:\我的开发环境\PHPEnv会导致 Apache 启动失败，错误日志里常出现Cannot load modules/mod_php7.so - 首次启动后，点「软件管理」→ 找到要装的 PHP 版本（如
php-8.3.13）→ 点安装，别手动解压或复制 bin 目录 - 如果浏览器打不开
localhost，先点主界面右上角「端口检测」，若 80 端口被占用，改 Apache 端口为8080，然后访问http://localhost:8080
macOS/Linux 用户：PATH 和 init 必须写对配置文件
很多人卡在 phpenv --version 报 command not found，问题几乎全出在 Shell 配置文件没选对或内容写错：
立即学习“PHP免费学习笔记（深入）”；
- Bash 用户（
~/.bash_profile或~/.bashrc）加这两行：export PATH="$HOME/.phpenv/bin:$PATH"eval "$(phpenv init -)" - Zsh 用户（macOS Catalina 及以后默认）必须改
~/.zshrc，写成~/.bash_profile白搭 -
exec $SHELL -l不生效？换成source ~/.zshrc（或对应文件）立刻验证 - 初始化后如果
phpenv versions显示空，说明插件没装：git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build
项目级版本指定：.php-version 文件最可靠
用 phpenv local 8.3.13 设置后切目录失效？大概率是没生成 .php-version 文件，或者文件权限不对：
- 执行
phpenv local 8.3.13后，当前目录下会自动生成.php-version，内容就是8.3.13（纯文本，无空格无换行） - 如果手动创建该文件，请用
echo "8.3.13" > .php-version，别用记事本保存，容易带 BOM 或 CRLF 换行 - Git 提交时记得把这个文件一起提交，团队协作时其他人 checkout 后自动匹配版本，比口头约定靠谱得多
- 注意：该文件只对当前目录及子目录生效，上级目录的
.php-version不会继承
最容易被忽略的是：Windows 的 PHPEnv 修改 PHP 版本靠图形界面点选，而 phpenv 的 global/local/shell 是三级优先级叠加关系，shell 会覆盖 local，local 覆盖 global——调试时如果版本不对，先运行 phpenv version（注意末尾带 s 是列表，不带才是当前实际生效的）看清楚哪一层在起作用。
