phpenv 安装必须通过 git clone 源码构建，禁用第三方exe/zip镜像；配置需同时设置PATH和eval "$(phpenv init -)"；版本切换遵循shell＞local＞global优先级，编译失败多因本地依赖缺失。
phpEnv 没有官方“最新镜像下载”渠道，所谓“镜像”多是第三方打包或误传的非标准版本，直接使用风险高——比如混入后门、缺少更新、不兼容新版 macOS/Linux 或 Windows 10/11 的权限模型。真正可靠的方式是通过源码克隆 + 本地构建，全程可控。
phpenv 安装必须用 git clone，别信 exe 或 zip 镜像包
所有声称提供“phpEnv 最新镜像下载”的网站（尤其是带 .cn 域名或百度网盘链接的），基本都不是 phpenv 项目本身。真正的 phpenv 是 GitHub 上由社区维护的开源工具（仓库地址：https://github.com/phpenv/phpenv），主分支已归档，但活跃镜像在 GitCode：https://gitcode.com/gh_mirrors/ph/phpenv。
- Windows 用户若看到
phpenv.exe或phpenv-setup.zip，大概率是封装了 Apache+MySQL 的 PHPEnv（注意大小写）——那是另一个国产集成环境，和 phpenv 无关 - Linux/macOS 用户若用
curl | bash一键安装脚本（如phpenv-installer），需确认脚本来源是否为原始仓库；目前该 installer 已多年未更新，phpenv install在较新系统上常因 OpenSSL 版本不匹配失败 - 直接克隆更安全：
git clone https://gitcode.com/gh_mirrors/ph/phpenv ~/.phpenv，然后手动配置 shell
bash/zsh 环境变量配置容易漏掉 eval 行
只加 PATH 不够，phpenv init - 输出的是 shims 和自动补全逻辑，跳过这步会导致 php 命令始终调用系统默认 PHP，phpenv versions 显示空或报错。
- Bash 用户写入
~/.bashrc：export PATH="$HOME/.phpenv/bin:$PATH"+eval "$(phpenv init -)" - Zsh 用户写入
~/.zshrc，内容完全一样 - 改完必须执行
source ~/.bashrc（或source ~/.zshrc），exec $SHELL -l会重置部分环境变量，反而可能失效 - 验证：运行
phpenv --version有输出，且which php返回路径含.phpenv/shims/php
phpenv install 编译失败最常见三个原因
phpenv install 8.3.13 卡在 configure 或 make 阶段，90% 以上不是网络问题，而是本地依赖缺失或版本冲突。
立即学习“PHP免费学习笔记（深入）”；
- 缺编译工具链：
build-essential（Ubuntu/Debian）、gcc make autoconf（CentOS/RHEL）、Xcode Command Line Tools（macOS） - 缺 OpenSSL 头文件：
libssl-dev（Debian系）或openssl-devel（RHEL系）；macOS 上若用 Homebrew 安装过 OpenSSL 3.x，需指定路径：CONFIGURE_OPTS="--with-openssl=/opt/homebrew/opt/openssl@3" phpenv install 8.3.13 - SQLite 支持被禁用：某些 Linux 发行版默认不装
libsqlite3-dev，导致 PDO_SQLite 扩展无法启用，后续 Composer 报错Class 'PDO' not found
切换版本后 php -v 不变？检查 local/global/shell 优先级
phpenv 的版本生效顺序是：shell > local（当前目录 .php-version） > global。设了 phpenv global 7.4.33 却仍看到 8.2，说明当前目录存在 .php-version 文件，或之前执行过 phpenv shell 8.2.0 未清除。
- 查当前生效层级：
phpenv version（注意末尾无 s） - 删会话级设置：
phpenv shell --unset - 删项目级设置：
rm .php-version - 全局设回 8.3：
phpenv global 8.3.13，再进子目录测试
真正麻烦的从来不是安装步骤本身，而是不同系统对 OpenSSL、ICU、libxml2 的版本容忍度差异——同一套命令，在 Ubuntu 24.04 上成功，在 macOS Sonoma 上可能因 libiconv 冲突失败。建议首次安装前先跑 phpenv install --list 看支持哪些版本，避开带 rc 或 alpha 的测试版。
