phpenv安装失败主因是PATH与phpenv init未配对：Bash用户改~/.bashrc，Zsh用户必须改~/.zshrc；需确认~/.phpenv/bin在PATH中且phpenv init -输出有效函数；装php-build插件、补全编译依赖、运行phpenv rehash为必做步骤。
phpenv 安装失败：PATH 和 init 没配对就白忙
绝大多数安装后 phpenv 命令找不到，根本原因不是克隆错了仓库，而是 PATH 和 phpenv init - 没在同一个 shell 配置文件里生效。
你用的是 Bash 还是 Zsh？别猜，直接查：echo $SHELL。Bash 用户改 ~/.bash_profile 或 ~/.bashrc；Zsh 用户必须改 ~/.zshrc —— 混用会导致 phpenv 命令存在但 shims 不工作，php -v 仍显示系统自带版本。
- 先确认
~/.phpenv/bin在PATH里：echo $PATH | grep phpenv - 再确认
phpenv init -输出是否被正确执行：phpenv init -应该输出一段 shell 函数定义，不是报错或空行 - 改完配置后，别用
exec $SHELL -l硬重启，优先试source ~/.zshrc（或对应文件），更可控
phpenv install 报错：缺依赖、没插件、权限卡死
phpenv install 8.3.13 失败，90% 是因为没装 php-build 插件，或系统缺少编译工具链。它不报“缺插件”，只报 configure 错误或 curl 下载失败，非常误导。
- 必须手动装插件：
git clone https://github.com/php-build/php-build $(phpenv root)/plugins/php-build - Ubuntu/Debian 系统必备：
sudo apt install build-essential libxml2-dev libssl-dev libsqlite3-dev libcurl4-openssl-dev libjpeg-dev libpng-dev libfreetype6-dev - macOS 用户用 Homebrew：
brew install autoconf automake libtool pkg-config openssl@3 sqlite3 curl jpeg pngquant freetype，注意 OpenSSL 版本要匹配 PHP 构建要求 - 非 root 用户安装时，确保
$(phpenv root)目录可写，否则编译中途会因权限拒绝退出
版本切不生效：local / global / shell 三层逻辑容易串
phpenv local 7.4.33 后 php -v 还是 8.3，不是命令没运行，而是当前目录下有 .php-version 文件被忽略，或上层目录也存在同名文件导致覆盖。
立即学习“PHP免费学习笔记（深入）”；
-
phpenv local会在当前目录生成.php-version，内容就是版本号（如7.4.33），不能带空格或换行 - 执行
phpenv version查看「当前生效版本」，它会明确告诉你来源是local、global还是shell -
phpenv shell 8.0.1是临时会话级设置，关掉终端就失效；phpenv global写入的是~/.phpenv/version，影响所有未设 local 的目录 - 若多个项目嵌套（比如
~/work/project-a/submodule），子目录的.php-version优先级最高，但父目录的设置不会自动继承
shim 机制失效：php -v 正确但 composer / phpunit 找不到扩展
装好 PHP 8.3 后 php -v 显示正常，但 composer install 报 ext-zip not loaded，说明 phpenv 调用的是正确二进制，但加载的 php.ini 不是该版本专属路径下的那个。
- 每个 PHP 版本的配置文件在
$(phpenv root)/versions/8.3.13/etc/php.ini，不是系统全局的/etc/php - 检查实际加载的 ini 文件：
php --ini，输出应包含类似Loaded Configuration File: /home/user/.phpenv/versions/8.3.13/etc/php.ini - 装扩展（如 xdebug）必须针对当前版本运行：
pecl install -s xdebug，然后手动在对应php.ini中加zend_extension=xdebug.so - 每次新装 PHP 版本后，务必运行
phpenv rehash，否则php、php-cgi等 shim 符号链接不会更新
phpenv rehash —— 它不报错，但不执行就等于没装完；还有人把 .php-version 放错目录层级，以为进了项目根目录就行，其实得确保 pwd 输出路径和 phpenv version 显示的 local 路径完全一致。 
