phpenv切换失败主因是环境变量未生效或shims未重建：需确保PATH包含~/.phpenv/bin且执行eval "$(phpenv init -)"激活，再运行phpenv rehash重建shims，否则php -v仍指向旧版本路径。
phpenv 切换失败，90% 是环境变量没生效或 shim 没重建，不是版本没装好。
phpenv 命令找不到：PATH 和 init 没配对
装完 phpenv 后输 phpenv 报 “command not found”，说明 shell 根本没加载它。常见原因有三个：
-
~/.phpenv/bin没加进$PATH—— 检查echo $PATH里有没有这串路径 -
eval "$(phpenv init -)"没执行 —— 这行才是激活 shims 和自动切换的核心，光加 PATH 不够 - 改了
~/.zshrc却用bash启动终端，或者反之 —— 先确认echo $SHELL，再改对应配置文件
修复方法：在 ~/.zshrc（或 ~/.bashrc）末尾追加两行：
export PATH="$HOME/.phpenv/bin:$PATH" eval "$(phpenv init -)"
然后运行 source ~/.zshrc，再试 phpenv --version。
立即学习“PHP免费学习笔记（深入）”；
phpenv global / local 切换后 php -v 不变
命令执行成功，但 php -v 还是旧版本，本质是 php 命令没走 phpenv 的 shim 路径。典型表现是 which php 返回 /usr/bin/php 或 /opt/homebrew/bin/php，而不是 ~/.phpenv/shims/php。
- 先确认
phpenv versions是否列出目标版本，且前面有星号（*）标出当前生效版本 - 如果没星号，说明
phpenv global 8.3.13没真正生效，重跑一遍并检查输出有没有报错 - 如果有星号但
which php仍不对，立刻执行phpenv rehash—— 这会重建所有 shim 文件，不执行就切不动 - 某些 shell（如 zsh）会缓存命令路径，
rehash后仍无效？直接关终端重开，比猜更省时间
安装 PHP 版本后无法切换：build 插件和依赖缺位
phpenv install 8.3.13 成功，但 phpenv versions 不显示它，或者显示为灰色未激活状态 —— 大概率是 php-build 插件没装，或系统缺少编译依赖。
- 检查插件是否就位：
ls ~/.phpenv/plugins/应该有php-build目录；没有就运行：git clone https://github.com/php-build/php-build.git ~/.phpenv/plugins/php-build - macOS 上常见缺失：
xcode-select --install、brew install autoconf automake libtool pkg-config - Linux（Ubuntu/Debian）缺依赖：
sudo apt-get install build-essential libxml2-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev - 装完依赖别忘了再跑一次
phpenv install 8.3.13，失败时看日志：tail -n 50 ~/.phpenv/plugins/php-build/share/php-build/log/8.3.13.log
项目级切换失效：.php-version 文件权限或位置错
在项目目录下执行 phpenv local 7.4.33，退出再进入却没自动切 —— phpenv 默认只认当前目录及所有父目录中的 .php-version，且文件必须可读。
- 确认文件存在：
cat .php-version应输出7.4.33（不能带空格、换行、注释） - 检查文件权限：
ls -l .php-version，确保不是----------这种全无权限 - 注意路径深度：如果你在
~/project/src下执行phpenv local，生成的文件在src/.php-version，但phpenv只向上找，不会向下进子目录生效 - 临时验证：进项目目录后手动运行
phpenv version，看输出是否匹配预期；不匹配就说明没读到文件
最易被忽略的是 rehash 和 init 的配合 —— 它俩不一起用，phpenv 就只是个摆设命令。切换前先 phpenv rehash，配置里漏了 eval "$(phpenv init -)"，再怎么装版本也白搭。
