phpenv命令找不到的主因是PATH与phpenv init输出路径不一致，需确保export PATH中路径（如~/.phpenv/bin）与eval "$(phpenv init -)"实际生成路径完全匹配，并正确重载对应shell配置文件。
phpenv 命令找不到：PATH 和 init 配置必须对齐
安装完 phpenv 后输入命令提示 command not found，90% 是因为 PATH 和 phpenv init - 两处没配对。不是只加 bin 就行——phpenv init - 输出的路径必须和你 export PATH 的路径一致，否则 shim 机制根本不会被加载。
常见错误组合：
-
git clone到~/.phpenv，但export PATH写成了$HOME/phpenv/bin（少了个点） -
eval "$(phpenv init -)"放在~/.bashrc，却用source ~/.profile重载（配置文件没生效） - Zsh 用户误把配置写进
~/.bashrc，而默认 shell 是zsh
验证方法：echo $PATH 看是否含 ~/.phpenv/bin；再执行 which phpenv，有输出才算真正就位。
phpenv install 失败：缺依赖比缺网络更常见
编译 PHP 时卡在 configure 或 make 阶段，报错里带 libxml2.h not found、openssl/ssl.h 或 readline.h，说明系统头文件缺失，不是网络问题，也不是 phpenv 本身 bug。
立即学习“PHP免费学习笔记（深入）”；
Ubuntu/Debian 系统必须提前装全这些：
-
build-essential（gcc、make 等基础编译链） -
libxml2-dev（DOM、SimpleXML 等扩展依赖） -
libssl-dev（cURL、OpenSSL 扩展必需） -
libreadline-dev（PHP CLI 交互式支持） -
zlib1g-dev（gzip、zip 扩展依赖） -
libcurl4-openssl-dev（cURL 编译支持）
一条命令搞定：sudo apt-get install -y build-essential libxml2-dev libssl-dev libreadline-dev zlib1g-dev libcurl4-openssl-dev。Mac 用户用 brew install openssl@3 readline zlib，并注意设置 PHP_BUILD_CONFIGURE_OPTS 指向 brew 路径。
装完版本却切不动：rehash 不是可选项，是必做动作
phpenv install 8.3.13 成功后，phpenv versions 能看到新版本，但 phpenv global 8.3.13 后 php -v 还是旧版——这几乎一定是忘了 phpenv rehash。
原因很直接：phpenv 不是硬链接或改 PATH，而是靠 ~/.phpenv/shims 下的一堆代理脚本（shim）来拦截 php、phpize、pear 等命令。新版本装完，shim 目录里没有对应入口，调用就 fallback 到系统默认 PHP。
所以每次 install、uninstall 或手动删了 ~/.phpenv/versions/xxx，都必须立刻执行：
-
phpenv rehash（重新扫描所有版本，生成 shim） - 再验证：
which php应该输出~/.phpenv/shims/php，而不是/usr/bin/php
项目级版本不生效：.php-version 文件权限和位置很关键
执行 phpenv local 7.4.33 后进入项目目录，php -v 仍显示全局版本，先检查三件事：
- 当前目录下是否存在
.php-version文件（不是.php_version或其他变体） - 该文件内容是否只有一行、无空格、无 BOM：
7.4.33（不能是v7.4.33或7.4.33\n\n） - 文件权限是否允许读取：
ls -l .php-version，避免因 umask 导致创建为---------
如果用的是 Git 管理项目，建议把 .php-version 提交进仓库——这是团队统一环境最轻量的方式，比口头约定或文档更可靠。别指望 IDE 或编辑器自动识别它，生效完全依赖 shell 层的 phpenv hook。
最容易被忽略的是：shim 机制依赖 shell 的 prompt 命令触发（比如 cd 后自动检测 .php-version），如果你用的是非交互式 shell（如某些 CI runner、systemd service 或 tmux 新 pane），phpenv init - 的 hook 可能没加载，此时必须显式执行 eval "$(phpenv init -)" 或改用 phpenv shell 7.4.33 临时绑定。
