phpenv 正常工作需满足四点：正确初始化 shell 配置文件、统一 $PHPENV_ROOT 路径、安装后执行 phpenv rehash、项目级版本依赖 .php-version 文件且需初始化生效。
直接装就能用，但不按路径和初始化顺序来，phpenv 会根本找不到 PHP 版本、php 命令也不生效——这不是 bug，是 shims 机制没启动。
安装前必须确认 shell 配置文件位置
不同系统默认加载的配置文件不一样：.bashrc（Ubuntu/WSL）、.bash_profile（macOS 默认 Terminal）、.zshrc（macOS Catalina 及以后、iTerm2）。装错文件，phpenv init 就白写了。
- 运行
echo $SHELL看当前 shell 类型 - 再运行
ls -a ~ | grep -E "^(.bashrc|.bash_profile|.zshrc)$"确认哪个文件实际被读取 - 只往那个文件里追加环境变量和
eval "$(phpenv init -)"
安装命令别硬套，路径要统一
官方推荐把 phpenv 装到 $HOME/.phpenv，但如果你手动改过 $PHPENV_ROOT，所有后续命令都要跟着变。比如：
- 克隆时用了
git clone https://github.com/phpenv/phpenv.git ~/my-phpenv，就得先设export PHPENV_ROOT="$HOME/my-phpenv" -
PATH就得写成export PATH="$HOME/my-phpenv/bin:$PATH"，不是.phpenv/bin - 插件目录也得对应：php-build 要克隆到
$(phpenv root)/plugins/php-build，否则phpenv install会报command not found: phpenv-install
装完 PHP 版本后必须执行 phpenv rehash
这是最容易漏的一步。phpenv 不是直接替换 php 命令，而是通过 shims 目录下的代理脚本转发。新版本装完，shims 没更新，终端还是调用老版本甚至系统自带的 PHP。
立即学习“PHP免费学习笔记（深入）”；
- 每次运行
phpenv install X.Y.Z后，立刻跟一句phpenv rehash - 如果已装多个版本但
php --version总显示不对，先phpenv rehash，再phpenv global X.Y.Z -
which php应该返回类似/home/xxx/.phpenv/shims/php，而不是/usr/bin/php；如果不是，说明 shims 没生效
项目级版本控制靠 .php-version 文件，不是靠 cd 自动触发
phpenv local 8.3.13 看似方便，但它只是在当前目录写一个 .php-version 文件。这个文件不会自动被识别，除非你已经正确初始化了 shell（即 eval "$(phpenv init -)" 已运行且生效）。
- 检查是否生效：进项目目录后运行
phpenv version，输出应为8.3.13 (set by /path/to/project/.php-version) - 如果显示的是 global 版本或报错，先确认
cd后有没有触发重载——zsh 用户可能需要额外启用auto_cd或手动cd .刷新 -
.php-version文件内容只能有一行，纯文本，不能有空格、注释或 BOM 头，否则解析失败
真正卡住人的地方，往往不是“怎么装”，而是“哪一行配置没生效”或者“哪个 shim 没刷新”。遇到命令不响应、版本切不动，优先查 which php 和 phpenv version 的输出，比重装快十倍。
