你大概率不需要下载Windows版“PHPEnv”集成包，而应使用类Unix系统主流的phpenv（带横线）多版本管理工具；Windows用户推荐WSL2+phpenv或Docker方案。
直接说结论：你大概率不需要下载“PHPEnv”这个 Windows 一体式集成包，而是该用 phpenv（带横线）——它是类 Unix 系统（macOS/Linux）上主流的、可脚本化、可复现的 PHP 多版本管理工具。Windows 用户请改用 WSL2 + phpenv 或 docker，别碰那个带 GUI 的“PHPEnv.exe”。
phpenv 安装失败：PATH 和 init 没生效
最常见现象是执行 phpenv --version 报错 command not found。根本原因不是没装好，而是 shell 没读到配置。
- 确认你编辑的是当前 shell 正在用的配置文件：
~/.bash_profile（macOS 默认）、~/.zshrc（新 macOS）、~/.bashrc（多数 Linux） -
echo 'export PATH="$HOME/.phpenv/bin:$PATH"' >> ~/.zshrc和echo 'eval "$(phpenv init -)"' >> ~/.zshrc必须都写入同一文件 - 别只靠
exec $SHELL -l，更可靠的是新开一个终端窗口，再试which phpenv - 如果仍不行，手动运行
source ~/.zshrc看报错——常见于phpenv init -输出为空，说明~/.phpenv路径不对或权限不足
phpenv install 报错：缺编译依赖或 configure 失败
phpenv install 8.3.13 卡在 configure: error: xml2-config not found 这类错误，本质是系统缺少 PHP 编译所需的 dev 包，不是 phpenv 本身的问题。
- Ubuntu/Debian：装
libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev zlib1g-dev - macOS（Homebrew）：装
libxml2 openssl@3 curl jpeg pngquant freetype，再导出路径：export PATH="/opt/homebrew/opt/libxml2/bin:$PATH" - 不要跳过
phpenv rehash：每次install后必须运行，否则php命令找不到 shim - 自定义编译参数用
PHP_BUILD_CONFIGURE_OPTS，比如export PHP_BUILD_CONFIGURE_OPTS="--with-openssl=/opt/homebrew/opt/openssl@3"
版本切换不生效：local / global / shell 优先级搞混了
执行 php -v 显示的版本和 phpenv version 不一致？说明 shim 没接管 php 命令，或者层级被覆盖。
立即学习“PHP免费学习笔记（深入）”；
- 优先级从高到低：shell > local（
.php-version文件） > global -
phpenv local 7.4.33会在当前目录生成.php-version，内容就是7.4.33—— 别手写错格式，也不能多空格 -
phpenv shell 8.2.0只影响当前终端会话，关掉就失效；退出前可用phpenv shell --unset - 检查是否被其他工具干扰：比如
brew install php会把系统/opt/homebrew/bin/php写进 PATH，排在~/.phpenv/shims前面，导致 shims 失效
真正容易被忽略的是 .php-version 文件的 Git 提交问题：团队协作时，这个文件必须提交进仓库，但很多人把它加进了 .gitignore；还有人误以为 phpenv global 能解决一切，结果在项目里跑 composer install 时扩展加载失败——因为 global 版本没装对应扩展，而 local 才绑定完整环境。
