phpenv需克隆源码并配置shell环境，phpenv install命令依赖php-build插件，须手动安装；切换版本后php -v不变是因shims路径未优先加入PATH，需确认which php指向~/.phpenv/shims/php并执行phpenv rehash。
phpenv 不是下载安装包，而是克隆源码仓库 + 配置 shell 环境；直接下载二进制或双击安装会失败。
phpenv install 命令报 command not found
这是最常见的一环卡死问题：你克隆了仓库、改了 PATH，但 phpenv install 仍不可用 —— 因为 phpenv install 功能由插件提供，并非 phpenv 自带。
- 必须先安装
php-build插件：git clone https://gitcode.com/gh_mirrors/ph/php-build $(phpenv root)/plugins/php-build - 确认插件目录存在：
ls $(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 - 插件装好后，
phpenv install --list才能正常列出可用版本
切换 PHP 版本后 php -v 不变
本质是 shell 的 which php 指向了系统自带 PHP（如 /usr/bin/php），而非 phpenv 生成的 shim 文件。phpenv 的机制完全依赖 PATH 中 ~/.phpenv/shims 的优先级。
- 检查当前
php路径：which php—— 正确应返回~/.phpenv/shims/php - 若不是，说明
~/.phpenv/shims未被加到PATH开头，或eval "$(phpenv init -)"未生效 - 手动验证 shim 是否生成：
ls ~/.phpenv/shims/，应有php、phpize、php-config等文件 - 必要时强制重建：
phpenv rehash
项目级版本不自动生效（.php-version 文件无效）
phpenv 只在进入目录时读取 .php-version，且该文件内容必须是纯版本号（无空格、无前缀、无注释）。
立即学习“PHP免费学习笔记（深入）”；
- 文件位置必须在项目根目录，且名称严格为
.php-version（开头带点，无扩展名） - 内容只能是类似
8.3.13或7.4.33，不能写成php-8.3.13或8.3.13 # latest - 确保该目录下没有更高优先级的设置（如上层目录也有
.php-version，或已执行过phpenv shell） - 可运行
phpenv version查看当前生效的版本来源（显示8.3.13 (set by /path/to/project/.php-version)才算成功）
真正容易被忽略的是 phpenv init 输出的内容必须被 eval 执行——它不只是设置 PATH，还会 hook cd 命令、注入 shims 目录、监听目录变更。漏掉这步，所有“自动”功能都会静默失效。
