phpenv本身不支持自定义版本号如“8.3.13-myfork”，仅管理真实编译安装的PHP二进制；所谓“自定义”实指安装非官方PHP源码或编译时通过PHP_BUILD_CONFIGURE_OPTS传入configure参数。
phpenv 本身不提供“自定义版本号”功能，比如把 8.3.13 改成 8.3.13-myfork；它管理的是真实编译安装的 PHP 二进制，版本号来自源码包或构建过程。所谓“自定义”，实际指两种场景：一是安装非官方发布的 PHP 版本（如带补丁的分支、企业定制版），二是编译时传入特定 configure 参数。下面分情况说明怎么做、为什么这样、以及容易出错的地方。
怎么安装非标准 PHP 源码（如私有分支或 tarball）
phpenv 默认只识别 php.net 官方发布的版本列表（通过 phpenv install -l 查看）。如果你手上有自己打的 patch、Git 分支 tarball 或内部镜像地址，不能直接用 phpenv install x.y.z，得绕过版本校验走手动构建流程：
- 把源码包解压到临时目录，例如
~/src/php-8.3-custom - 进入该目录，手动运行 configure/make/make install，目标路径设为
$PHPENV_ROOT/versions/8.3-custom（注意路径必须匹配phpenv root输出） - 执行
phpenv rehash，让 shims 生效 - 验证：运行
phpenv versions应能看到8.3-custom，再用phpenv local 8.3-custom切换测试
关键点：路径名必须和你最终想用的版本标识一致；configure 的 --prefix 必须指向 $PHPENV_ROOT/versions/xxx，否则 phpenv 找不到二进制文件。
怎么在编译时加 --with-openssl 等 configure 参数
phpenv 依赖 php-build 插件完成编译，而参数控制靠环境变量 PHP_BUILD_CONFIGURE_OPTS。这不是可选配置，是必须显式设置的步骤：
立即学习“PHP免费学习笔记（深入）”；
- 先确保已安装插件：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - 导出参数：
export PHP_BUILD_CONFIGURE_OPTS="--with-openssl --with-zlib --enable-opcache" - 再执行安装：
phpenv install 8.3.13
注意：这个变量只对**后续一次**的 phpenv install 生效；如果忘了设，安装完才发现缺扩展，只能删掉重装（phpenv uninstall 8.3.13），不能事后追加。另外，某些参数（如 --with-apxs2）会引入 Apache 依赖，若系统没装 apache2-dev 或对应头文件，编译会直接失败，错误信息通常是 configure: error: apxs not found。
为什么 phpenv install 8.3.13 后 php -v 还是旧版本
最常见原因是漏了 phpenv rehash。phpenv 不是替换 PATH 里的 php，而是通过 shims 目录生成代理脚本（如 ~/.phpenv/shims/php），这些脚本在运行时才查当前生效版本。安装新版本后，shims 不会自动更新：
- 每次
phpenv install或phpenv uninstall后，必须手动执行phpenv rehash - 检查是否生效：运行
which php，输出应为~/.phpenv/shims/php，不是系统自带路径（如/usr/bin/php） - 如果
which php指向错误位置，说明 shell 初始化没生效，回头检查~/.bashrc或~/.zshrc里eval "$(phpenv init -)"是否已加载且无语法错误
另一个隐蔽问题是 .php-version 文件被 gitignore 掉了，或者项目根目录下存在同名但内容为空的文件，导致 phpenv local 实际没读到值，回退到全局版本——建议用 phpenv version 查当前解析结果，别只信 php -v。
CI/CD 中复现本地 phpenv 行为要注意什么
CI 环境（如 GitHub Actions、GitLab CI）通常用干净容器，没有交互式 shell，eval "$(phpenv init -)" 可能不生效，因为 phpenv 的 shim 机制依赖 shell 函数钩子。简单粗暴但可靠的做法是：
- 跳过
phpenv init，直接把~/.phpenv/shims加进 PATH：echo 'export PATH="$HOME/.phpenv/shims:$PATH"' >> $BASH_ENV - 用
phpenv global而不是phpenv local，避免依赖工作目录下的.php-version - 确认
phpenv install命令前已运行phpenv rehash，有些 CI 镜像会缓存 shims 导致旧版本残留
复杂点在于：不同 CI 平台对 shell 初始化的支持差异大，GitHub Actions 的 run 步骤默认用 non-login shell，~/.bashrc 不自动 source，所以依赖 eval 的方式容易静默失效。这时候硬写 PATH 是更可控的选择。
