Hyperf多版本共存不能依赖phpenv/phpbrew等PHP版本切换工具，因其仅管理PHP二进制，不处理Swoole编译、pcntl/posix扩展启用及glibc兼容性；必须为每个项目显式指定PHP路径（如/usr/bin/php8.1）并确保swoole启用coroutine，否则启动失败或协程失效。
Hyperf 项目不能靠“切换全局 PHP 版本”来适配多版本环境，必须让每个项目绑定专属的 PHP 解释器路径和扩展状态 —— 否则 php bin/hyperf.php start 很可能用错版本、加载不到 swoole，或者协程直接失效。
为什么 phpenv / phpbrew 不适合 Hyperf 多版本共存
phpenv 等工具只管 PHP 二进制切换，不处理 Swoole 编译、pcntl / posix 扩展启用、glibc 兼容性等底层依赖。Hyperf 启动时若发现 swoole 未加载或 coroutine => enabled 缺失，会静默退出或报 Fatal error: Uncaught Swoole\Exception: event loop has already been created。
常见踩坑点包括：
-
php --ri swoole输出里没有coroutine => enabled—— 这是根本门槛，其他都白搭 - 用
phpenv use 8.1切换后，supervisor或systemd仍调用系统默认/usr/bin/php - 热重载（
server:watch）子进程继承了错误的PHP_BINARY，导致 reload 后运行在 PHP 8.0 上，但项目 require 了 PHP 8.1+ 的语法
启动命令必须显式指定 PHP 路径
所有入口操作，包括开发启动、定时任务、迁移、测试，都要带完整 PHP 路径，不能依赖 PATH 或 shell 别名。
立即学习“PHP免费学习笔记（深入）”；
正确写法示例：
sudo /usr/bin/php8.0 bin/hyperf.php start /usr/bin/php8.1 bin/hyperf.php migrate /usr/bin/php8.1 vendor/bin/phpunit
关键点：
- Ubuntu/Debian 下通常为
/usr/bin/php8.0、/usr/bin/php8.1；CentOS/RHEL 是/opt/rh/php81/root/usr/bin/php类路径 - 不要用
php命令裸调，哪怕你刚执行过phpenv use 8.1 - Supervisor 配置中必须写死
command=/usr/bin/php8.1 bin/hyperf.php start，并删掉environment=PATH=...这类干扰项
composer install 必须匹配目标 PHP 版本
composer install 不只是下载包，它还会根据当前 PHP 版本解析 platform 配置、触发 post-autoload-dump 脚本、生成 classmap —— 若用 PHP 8.0 装出的 vendor，在 PHP 8.1 下跑可能因注解解析失败而 crash。
建议流程：
- 先确认项目
composer.json中"config": {"platform": {"php": "8.1.0"}}与目标环境一致 - 用对应 PHP 调用 composer：
/usr/bin/php8.1 /usr/local/bin/composer install --no-dev --optimize-autoloader - 避免
composer global require，所有 devtool（如hyperf/devtool）都走本地--dev安装
Docker 是最省心的多版本落地方式
当服务器要同时跑 Hyperf v2（PHP 7.4–8.0）和 v3（PHP 8.1+），又不想手动维护多套 Swoole 编译产物时，Docker 几乎是唯一靠谱选择。
镜像选择逻辑：
- v2 项目 →
hyperf/hyperf:7.4-alpine-cli或hyperf/hyperf:8.0-apache - v3 项目 →
hyperf/hyperf:8.1-alpine-cli（已预装swoole+openssl+http2） - 所有镜像都确保
php --ri swoole | grep 'coroutine'返回enabled
注意：别自己 FROM php:8.1-cli 再手动 pecl install swoole —— Alpine 的 musl libc 和 glibc 环境下编译行为不一致，容易漏掉 --enable-sockets 导致 RPC 失败。
真正难的不是写 docker-compose.yml，而是确认每个容器里 php --ri swoole 的输出是否稳定包含 coroutine => enabled。只要这一行没出来，其他配置全得重来。
