phpenv切换本质是激活shim路径，需确保eval "$(phpenv init -)"已加载且which php指向~/.phpenv/shims/php；否则phpenv global/local将静默失效，常见原因包括配置文件未source、shell类型不匹配或.php-version格式错误。
phpenv 切换版本不是“切换”而是“激活”——它靠 shell shim 机制重写 php 命令的执行路径，所以必须确保环境变量和初始化已生效，否则所有 phpenv global、phpenv local 都会静默失败。
为什么 phpenv global 8.3.13 后 php -v 还是旧版本？
这是最常卡住的一步。根本原因不是命令没运行，而是 phpenv init - 的输出没被 shell 正确加载：
-
eval "$(phpenv init -)"必须写入 shell 配置文件（如~/.bashrc或~/.zshrc），且该配置文件已被 source 过 - 如果用的是 zsh 但改了
~/.bashrc，或者改完没执行source ~/.zshrc，php命令仍走系统原路径 - 检查是否生效：运行
which php，正确结果应为~/.phpenv/shims/php；如果是/usr/bin/php或/opt/homebrew/bin/php，说明 shim 未接管 - 临时验证：手动运行
eval "$(phpenv init -)"再试php -v，能切成功就说明是配置加载问题
phpenv local 不生效？检查项目根目录的 .php-version
phpenv local 8.3.13 实际只是在当前目录写一个纯文本文件 .php-version，内容就是 8.3.13。它的触发依赖两个条件：
- 你必须 cd 进入该目录（不能只靠路径参数或符号链接跳转）
- 该目录下必须存在
.php-version，且内容不含空格、换行或注释（例如不能是8.3.13 # dev） - 父目录的
.php-version不会继承，子目录也不会自动继承——它是严格基于当前工作目录向上查找的第一个匹配文件 - 可以用
phpenv version查看当前实际解析出的版本（含来源路径），比php -v更准
phpenv install 失败常见堵点
安装新版本 PHP 是最易出错的环节，报错往往藏在编译日志末尾，但根源集中在三类：
立即学习“PHP免费学习笔记（深入）”；
- 缺编译依赖：Ubuntu/Debian 上至少要
sudo apt install autoconf bison libxml2-dev libcurl4-openssl-dev libssl-dev libreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev libpcap-dev libncurses5-dev libexpat1-dev libpcre3-dev；macOS 用 Homebrew 要先brew install autoconf automake openssl@3 curl sqlite3 readline icu4c - OpenSSL 版本冲突：PHP 8.3+ 默认要求 OpenSSL 3.x，若系统只有 OpenSSL 1.1，需显式指定：
export PHP_BUILD_CONFIGURE_OPTS="--with-openssl=/opt/homebrew/opt/openssl@3"（macOS）或--with-openssl=/usr/lib/x86_64-linux-gnu（Ubuntu） - 内存不足导致
make中断：虚拟机或小内存机器上建议加-j1参数限制并发编译：phpenv install --configure-options="--enable-opcache" 8.3.13后手动进$(phpenv root)/versions/8.3.13执行make -j1 && make install
全局、本地、shell 级版本优先级怎么算？
phpenv 按固定顺序查找并应用版本，高优先级会覆盖低优先级：
-
phpenv shell 8.2.12设置的版本最高（仅当前终端 session 有效，写入$PHPENV_VERSION环境变量） -
.php-version文件次之（项目级，从当前目录逐级向上找，找到即停） -
phpenv global 8.3.13最低（写入~/.phpenv/version，兜底用） - 注意：
phpenv shell --unset可清除 shell 级设置；phpenv local --unset删除.php-version；但phpenv global --unset不清空文件，只是设为空字符串，此时会 fallback 到系统默认php
真正麻烦的不是命令记不住，而是 shim 机制对 shell 环境极度敏感——一次 source 忘记、一个 which php 没核对、一个 .php-version 多了个空格，都会让切换看起来“没反应”。动手前先跑通 which php 和 phpenv version，比反复重装快得多。
