php-build是phpenv实现PHP多版本编译安装的核心插件，必须克隆至$(phpenv root)/plugins/php-build目录，否则phpenv install命令不可用；其依赖正确权限、shell初始化及shim重建。
php-build 是必须装的核心插件
没有 php-build，phpenv install 命令根本不能用——它不是内置功能，而是靠这个插件实现 PHP 源码编译安装的。官方仓库不带编译逻辑，所有版本安装都依赖它。
安装方式固定，路径必须精准：
git clone https://github.com/php-build/php-build.git $(phpenv root)/plugins/php-build
常见错误包括：
- 克隆到错目录（比如
~/.phpenv/plugins/外的任意位置），phpenv install会直接报command not found: phpenv-install - 权限问题：如果
$(phpenv root)是 root 所有（如装在/usr/local/phpenv），普通用户无法写入plugins/目录，得改用sudo或换用户安装 - 插件未激活：部分旧版 shell 配置漏掉
eval "$(phpenv init -)"，会导致插件命令不加载
phpenv-local-version 提供项目级自动切换增强
原生 phpenv local 只是生成 .php-version 文件，但不会在进入子目录时自动识别。这个插件能监听当前路径，只要子目录里有 .php-version 就触发切换（类似 rbenv 的 ruby-local-version 行为）。
立即学习“PHP免费学习笔记（深入）”；
使用场景很具体：
- 大型 monorepo 里不同子模块要求不同 PHP 版本（如
backend/用 8.2，legacy-api/用 7.4） - 不想每次 cd 都手动
phpenv local，希望进目录即生效
安装后无需额外配置，但要注意：
- 它依赖 shell 的
chpwd钩子（zsh）或PROMPT_COMMAND（bash），某些精简 shell（如 alpine 的ash）不支持 - 与
direnv冲突：如果同时启用，可能重复触发或互相覆盖
phpenv-hooks 用于自动化构建前后动作
phpenv-hooks 不是独立插件，而是 phpenv 自带的钩子机制，但需要显式启用才能起作用。它允许你在 install、uninstall、global 等命令执行前后插入自定义脚本。
典型用途：
- 安装完新版本后自动
pecl install xdebug - 切换全局版本时自动重启 php-fpm（需 sudo 权限）
- 卸载前备份
php.ini或扩展配置
启用方式：
eval "$(phpenv hooks install)"
钩子脚本必须放在 $(phpenv root)/hooks/ 下，命名规则严格：phpenv-<command>-<stage></stage></command>，例如：
-
phpenv-install-post：安装成功后执行 -
phpenv-global-pre：执行phpenv global前运行
注意：钩子脚本本身是 shell 脚本，不能用 PHP 写；且 stage 名称拼写错误（如写成 post-install）会导致静默失效。
自定义插件要注意 PATH 和 shim 重建
自己写的插件（比如封装常用 composer + php 组合命令）必须满足两个硬性条件才能被识别：
- 文件名以
phpenv-开头，且有可执行权限（chmod +x） - 放在
$(phpenv root)/plugins/<plugin-name>/bin/</plugin-name>下，而不是插件根目录
否则即使 phpenv --version 能看到插件名，执行时仍提示 command not found。另外，插件新增命令后，必须手动运行：
phpenv rehash
否则 phpenv 的 shim 机制不会生成对应可执行链接，shell 找不到命令入口。这点容易被忽略，尤其在 CI 环境中临时加插件时。
