phpenv install 不生效需先确认是否安装 php-build 插件，因该命令由插件提供；未安装则执行 git clone 命令手动添加，并通过 phpenv commands 验证是否含 install；随后检查依赖（macOS 用 brew，Linux 用 apt）、执行 phpenv rehash 更新 shims，确保 .php-version 文件位置正确且未被 shell 级别锁定。
phpenv install 命令不生效？先确认是否装了 php-build 插件
phpenv 本身不带编译 PHP 的能力，phpenv install 是由 php-build 插件提供的。如果你执行 phpenv install 8.3.13 报错 “command not found” 或提示找不到版本，大概率是插件没装。
- 手动安装插件：
git clone https://gitcode.com/gh_mirrors/ph/php-build $(phpenv root)/plugins/php-build - 验证是否加载成功：
phpenv commands输出里应包含install - macOS 用户注意：需提前装好
autoconf、openssl、libxml2等依赖（用 Homebrew：brew install autoconf openssl libxml2） - Linux（如 Ubuntu）需装 build-essential、libssl-dev、libxml2-dev 等，否则编译直接失败
怎么装一个非官方列表里的 PHP 版本（比如 8.4.0RC3 或私有 patch 版）
php-build 支持从源码 URL 或本地 tarball 安装，不依赖内置版本列表。关键在指定 --definition 或直接传路径。
- 用自定义 definition 文件（推荐）：
phpenv install --definition /path/to/my-php-8.4.0rc3.definition 8.4.0RC3 - 从指定 tarball 编译：
phpenv install --tarball https://downloads.php.net/~derick/php-8.4.0RC3.tar.gz 8.4.0RC3 - 本地源码目录编译（适合调试 patch）：
phpenv install --source /path/to/php-src 8.4.0-patched - 所有方式都支持环境变量控制编译选项，例如：
PHP_BUILD_CONFIGURE_OPTS="--with-openssl=/opt/homebrew/opt/openssl" phpenv install 8.4.0RC3
.php-version 文件不触发切换？检查作用域优先级和文件位置
phpenv 按“shell → local → global”顺序决定当前 PHP 版本，而 local 级别依赖项目根目录下的 .php-version 文件。但它只认当前工作目录或其任意父目录中的该文件 —— 不会向上跨挂载点，也不会读子目录。
- 确保
.php-version在你cd进入的项目根目录下，内容只有一行，如：8.3.13（不能带空格或注释） - 如果终端已用
phpenv shell 7.4.33锁定，.php-version就被忽略 ——phpenv shell --unset可解除 - 运行
phpenv version查看当前生效来源（输出类似8.3.13 (set by /path/to/project/.php-version)） - zsh 用户若发现自动切换失效，检查是否漏加
eval "$(phpenv init -)"到~/.zshrc（而非仅~/.bashrc）
多个版本共存但 php -v 总显示老版本？重生成 shim 是关键
phpenv 通过 shims（轻量代理脚本）拦截 php、phpize 等命令，并按当前上下文调用对应版本二进制。一旦新版本装完却没更新 shim，就仍走旧路径。
立即学习“PHP免费学习笔记（深入）”；
- 每次运行
phpenv install后，必须执行：phpenv rehash - 如果改过
~/.phpenv/versions/下的目录名或手动移动过版本目录，也必须rehash - shim 默认生成在
~/.phpenv/shims/，可手动检查该目录下是否有php文件，且权限为可执行 -
which php应返回~/.phpenv/shims/php；若返回系统路径（如/usr/bin/php），说明 PATH 或 init 未生效
rehash 漏掉、shim 路径没进 PATH、或 .php-version 放错位置。这三个点对齐了，多版本切换就稳了。 
