phpenv本身不托管PHP二进制包，而是通过php-build插件下载官方源码（如php-8.3.13.tar.xz）并本地编译安装；切换版本后php -v不变主因是~/.phpenv/shims未被优先纳入PATH，需确保其在PATH最前并执行phpenv rehash。
phpenv 本身不提供“各个版本下载”的功能——它不托管 PHP 二进制包，也不像 pyenv 那样内置大量预编译镜像。你真正要下载的是 PHP 源码（或通过插件间接拉取），而 phpenv 只负责编译、安装、切换和路由。搞错这点，90% 的安装失败就源于此。
phpenv install 命令实际在做什么
phpenv install 不是直接下载 ZIP 包解压，而是调用 php-build 插件，从官方源（https://www.php.cn/link/8416ebd086e39d2492a704f3e32eb198 或 https://www.php.cn/link/ad4f60ac8da51a4c9c75707b3a9c92dd PHP 源码压缩包（.tar.xz），然后本地编译安装。
- 它默认使用
<a href="https://www.php.cn/link/ec1859db271276d4081d7ca1f767258d">https://www.php.cn/link/ec1859db271276d4081d7ca1f767258d</a>地址 - 若网络不通（比如国内直连慢或被限），会卡在 “Downloading php-8.3.13.tar.xz…” 并超时
- 不支持指定镜像站，除非你手动改
php-build的定义文件或设环境变量
实操建议：
- 确保已安装
php-build插件：git clone https://gitcode.com/gh_mirrors/ph/php-build $(phpenv root)/plugins/php-build - 提前确认系统依赖齐全（Ubuntu/Debian）：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev - 如需加速，可临时设置国内镜像源（需 patch
php-build）或手动下载后放至$(phpenv root)/cache/目录，命名格式为php-8.3.13.tar.xz，再运行phpenv install 8.3.13—— 它会优先检查 cache
为什么 phpenv global / local 切换后 php -v 不变
这不是 phpenv 失效，而是 shell 的 PATH 查找顺序问题：系统自带的 /usr/bin/php 或 /opt/homebrew/bin/php（macOS）优先级高于 ~/.phpenv/shims/php。
立即学习“PHP免费学习笔记（深入）”；
常见错误现象：
-
phpenv version显示8.3.13 (set by /path/to/project/.php-version) - 但
php -v仍输出PHP 8.1.2 -
which php返回/usr/bin/php，而非~/.phpenv/shims/php
原因和解决：
- 检查
echo $PATH，确认~/.phpenv/shims是否在最前面（必须在/usr/bin之前） -
phpenv init -输出应包含export PATH="$HOME/.phpenv/shims:$PATH"—— 如果你的 shell 配置里只加了bin/路径，漏了shims/，就完全无效 - Zsh 用户注意：
~/.zshrc和~/.zprofile加载顺序不同，推荐把eval "$(phpenv init -)"放在~/.zshrc中，并执行source ~/.zshrc - 运行
phpenv rehash强制重建所有 shim 文件（尤其在新装 PHP 后）
项目级版本控制：.php-version 文件怎么写才生效
phpenv local 命令本质就是往当前目录写一个纯文本文件 .php-version，内容只能是 一行、无空格、无注释、无前后缀 的版本号。
正确写法：
8.3.13
这些都会导致失效：
-
php 8.3.13（多了php前缀） -
8.3.13\n（末尾有换行或空格） -
# use 8.3.13（含注释） -
8.3（不精确匹配已安装版本，phpenv不做模糊匹配）
验证方式：
- 进入项目目录后，运行
phpenv version—— 正确时显示8.3.13 (set by /path/to/project/.php-version) - 该文件会被 Git 跟踪，适合团队统一环境；但不要提交
.php-version到主干分支，除非明确要求全团队锁定该版本
phpenv 和系统 PHP 共存时最易忽略的细节
很多人以为 phpenv 是“替代”系统 PHP，其实它是“劫持”：所有对 php、phpize、pear 等命令的调用，都会经由 ~/.phpenv/shims/ 下的同名脚本转发到对应版本的二进制。
这意味着：
- 你不能直接删掉系统 PHP（比如
apt remove php），否则某些系统服务（如 Apache 的libapache2-mod-php）可能异常 -
php --ini显示的配置路径仍是当前激活版本的php.ini（通常在~/.phpenv/versions/8.3.13/etc/php.ini），不是/etc/php/8.1/cli/php.ini - 扩展（如
redis.so）必须为每个 PHP 版本单独编译安装，pecl install redis的结果只对当前激活版本生效 - 如果你用 Docker，
phpenv完全不生效 —— 容器内没有它，别指望靠宿主机的phpenv控制容器里的 PHP 版本
真正的复杂点不在安装，而在理解「shim 层」如何介入命令执行链。一旦 PATH 或 shim 缓存出问题，调试起来比重装还费时间。
