phpenv切换PHP环境靠shim机制动态路由，无需重启服务，但需确保初始化生效、.php-version文件规范且PATH中shims路径优先。
直接说结论：phpenv 切换 PHP 环境不是“改配置再重启服务”，而是靠 shim 机制在命令调用时动态路由到对应版本的二进制文件——所以切换是即时的、无感知的，但前提是环境已正确初始化，且没被系统自带 PHP 或其他管理工具（如 Docker、Homebrew PHP）干扰路径。
phpenv init - 后 shell 没生效？检查这三处
很多“切换不生效”问题其实卡在初始化这一步。执行 phpenv init - 输出的是 shell 片段，必须被实际加载，否则 php 命令根本不会走 phpenv 的 shim。
- 确认你编辑的是当前 shell 正在读的配置文件：
~/.bashrc（Bash）、~/.zshrc（Zsh），而不是~/.profile或~/.bash_profile（后者在某些终端启动模式下可能不被读取） -
eval "$(phpenv init -)"这行必须放在PATH设置之后，否则 shim 目录（$HOME/.phpenv/shims）无法优先于系统/usr/bin/php被命中 - 执行
source ~/.zshrc（或对应文件）后，运行which php，结果必须是$HOME/.phpenv/shims/php；如果不是，说明 shim 未接管
phpenv local 8.3.13 不起作用？先看 .php-version 文件位置和内容
项目级切换依赖 .php-version 文件，但它非常挑剔：
- 文件必须位于项目**根目录**（即你执行
cd进入后的当前路径），不能在子目录或父目录 - 文件内容只能是纯版本号，比如
8.3.13，**不能带空格、换行符、注释或前缀**（如php-8.3.13或v8.3.13都会失败） - 执行
phpenv local 8.3.13会自动创建该文件，但如果手动编辑过，建议用cat .php-version | od -c检查是否混入了不可见字符
phpenv install 报错编译失败？缺的不是 PHP 依赖，是系统头文件和构建工具
phpenv install 实际调用 php-build 编译源码，失败几乎都源于系统级缺失：
立即学习“PHP免费学习笔记（深入）”；
- Ubuntu/Debian：运行
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev libsqlite3-dev - macOS（Homebrew）：确保
openssl@3、sqlite3、libxml2已安装，并通过export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"等方式把头文件路径暴露给编译器 - 常见报错如
configure: error: Cannot find OpenSSL's <evp.h>或fatal error: 'zlib.h' file not found，都是头文件未就位的明确信号
php -v 显示旧版本，但 phpenv version 显示新版本？PATH 顺序错了
这是最隐蔽也最常被忽略的问题：phpenv version 显示的是 phpenv 认为“该用哪个”，而 php -v 执行的是 PATH 中第一个 php。两者不一致，基本等于 PATH 里有别的 PHP 在“抢跑”。
- 运行
echo $PATH，确认$HOME/.phpenv/shims出现在所有其他 PHP 路径（如/usr/local/bin、/opt/homebrew/bin、/usr/bin）之前 - 运行
which php和ls -la $(which php)，如果指向的是非 shim 路径（例如/usr/bin/php），说明 shim 未生效或被覆盖 - 临时验证：执行
export PATH="$HOME/.phpenv/shims:$PATH"再试php -v—— 若此时正常，就坐实了 PATH 顺序问题
真正麻烦的从来不是“怎么装多个 PHP”，而是让 shell 每次调用 php 时，都老老实实走 phpenv 的 shim 路由。路径顺序、初始化时机、.php-version 的洁净度，这三个点漏掉任何一个，都会让切换变成玄学。
