phpenv install失败主因是缺失php-build插件或系统依赖，需先安装插件并配置build-essential、libssl-dev等依赖，再用PHP_BUILD_MIRROR指定镜像源加速下载。
phpenv install 命令失败：常见原因和修复步骤
直接运行 phpenv install 8.2.12 报错“command not found”或“no such command”，大概率是没装 php-build 插件——phpenv 本身不带编译能力，所有版本安装都依赖这个插件。
- 检查插件是否已存在：
ls $(phpenv root)/plugins/php-build，若提示 no such file，需手动安装 - 正确安装方式（推荐用 git clone）：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 某些旧版
phpenv可能默认用~/.phpenv/plugins路径，执行前先确认phpenv root输出的实际路径 - 安装完插件后，无需重启 shell，但建议运行
phpenv rehash刷新 shims
安装 PHP 版本时依赖缺失：build-essential 和 dev 包必须装全
报错信息里出现 configure: error: no acceptable C compiler found 或 openssl/ssl.h: No such file or directory，说明系统缺少基础构建工具或头文件。
- Debian/Ubuntu 系统必须装：
sudo apt install build-essential libssl-dev libxml2-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev autoconf bison re2c - CentOS/RHEL 系统对应命令：
sudo yum groupinstall "Development Tools" && sudo yum install openssl-devel libxml2-devel curl-devel libjpeg-devel libpng-devel freetype-devel - macOS 使用 Homebrew：
brew install openssl@3 libxml2 curl jpeg pnglib freetype autoconf automake bison re2c，并注意设置PHP_BUILD_CONFIGURE_OPTS - 跳过测试套件可加快安装（尤其在 CI 环境）：
PHP_BUILD_TEST=false phpenv install 8.3.13
.php-version 文件不生效：目录层级和权限问题最常被忽略
在项目根目录放了 .php-version，但 php -v 仍显示全局版本，不是配置写错，而是 phpenv 没读到它。
-
phpenv只从当前工作目录向上逐级查找.php-version，不会跨挂载点或符号链接目录（比如/var/www是挂载的 NFS 卷就可能失效） - 文件内容只能是纯版本号，不能带空格、注释或换行符：
8.2.12✅，# php 8.2❌，8.2.12\n❌ - 确保文件权限可读：
chmod 644 .php-version；若用 root 写入，普通用户 cd 进去会因权限拒绝读取 - 验证是否被识别：
phpenv version-name应输出当前匹配的版本号；若输出system，说明没找到有效配置
安装慢 / 中途失败：源码下载卡在 php.net 或 pecl.php.net
国内网络直连 php.net 极不稳定，phpenv install 默认从官网拉源码包，超时或校验失败很常见。
立即学习“PHP免费学习笔记（深入）”；
- 临时改镜像源（仅本次安装生效）：
PHP_BUILD_MIRROR=https://php.net/distributions phpenv install 8.1.27 - 更可靠的做法是预下载好 tar.gz 包，放到
$(phpenv root)/cache/目录下，文件名必须严格匹配（如php-8.1.27.tar.gz），phpenv会自动优先使用缓存 - 若需长期切换源，可在
~/.bashrc中设置环境变量：export PHP_BUILD_MIRROR="https://mirrors.huaweicloud.com/php/" - 注意：部分镜像站不同步所有版本（比如只同步最新 3 个 minor 版），查不到版本时先
phpenv install --list | grep 8.1确认可用性
实际用下来，最难调的往往不是命令输错，而是插件没装、依赖缺一个头文件、或者 .php-version 文件藏在子目录却误以为父目录生效——这些点不跑一遍真容易卡住半天。
