结论：不能只用 phpenv global，因微服务多项目需不同PHP版本，而phpenv版本优先级为shell > local > global，未显式设置local或创建.php-version时默认仅生效global；必须为每个项目配置.php-version文件并执行phpenv rehash才能实现可靠隔离。
直接说结论：用 phpenv 搭建本地多版本微服务开发环境是可行的，但必须配合项目级隔离 + 显式版本声明，不能只靠全局切换。
为什么不能只用 phpenv global
微服务通常由多个独立 PHP 项目组成（如 auth-service、payment-service），它们可能依赖不同 PHP 版本（比如一个用 8.1，另一个因 SDK 限制卡在 7.4）。如果只设 phpenv global 8.1，进到 7.4 项目目录时 PHP 仍会执行 8.1 —— phpenv 不会自动降级，除非你显式设置本地版本。
- 根本原因：
phpenv的版本匹配优先级是：shell > local > global。没做任何设置时，它只认 global - 常见错误现象：
cd payment-service && php -v依然显示 8.1，但 composer install 报 extension 不兼容 - 真正起作用的是
.php-version文件或phpenv local命令，不是目录自动感知
每个微服务项目必须有 .php-version
这是最稳定、CI 友好、团队可复现的方式。它比 phpenv local 更可靠，因为后者只写入当前 shell 的环境变量，不持久化也不进 Git。
- 在
auth-service/根目录执行：echo "8.3.13" > .php-version - 在
payment-service/根目录执行：echo "7.4.33" > .php-version - 确保
.php-version文件被提交到 Git —— 这是团队统一环境的关键 - 验证方式：
cd auth-service && phpenv version应输出8.3.13 (set by /path/to/auth-service/.php-version)
phpenv install 前必须装好系统依赖
PHP 编译失败是新手卡住最多的地方，尤其在 macOS 或较新 Linux 发行版上。报错常为 configure: error: no acceptable C compiler found 或 libxml2 not found，这不是 phpenv 的问题，而是缺编译链和头文件。
立即学习“PHP免费学习笔记（深入）”；
- Ubuntu/Debian：
sudo apt-get install -y autoconf bison build-essential libssl-dev libcurl4-openssl-dev libreadline-dev zlib1g-dev libxml2-dev libsqlite3-dev - macOS（Homebrew）：
brew install autoconf automake openssl@3 libxml2 libzip sqlite3，再导出：export PATH="/opt/homebrew/opt/openssl@3/bin:$PATH"和export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig" - 安装完务必运行：
phpenv rehash，否则新装的php命令不会出现在PATH中
调试时别忽略 which php 和 phpenv version 的差异
这两个命令输出不一致，基本等于环境没理干净。典型场景：你在 auth-service 目录下执行 phpenv version 显示 8.3.13，但 which php 指向 /usr/bin/php（系统自带）—— 那所有 php 命令实际都绕过了 phpenv。
- 原因：别的地方（比如
/etc/profile或其他 shell 配置）把系统/usr/bin放到了PATH更前面 - 修复方法：
echo $PATH看顺序，确保$HOME/.phpenv/shims在最前（phpenv init -输出里会提示该路径） - 临时验证：
export PATH="$HOME/.phpenv/shims:$PATH"，再试which php是否变成~/.phpenv/shims/php
最易被忽略的一点：shim 机制依赖 ~/.phpenv/shims 目录下的符号链接，而这个目录只有在运行 phpenv rehash 后才会生成或更新。哪怕你已用 phpenv install 成功编译了 PHP，只要没 rehash，终端就找不到那个版本的 php 命令 —— 它不是“安装完就自动可用”，而是“安装完+rehash 才可用”。
