Hyperf 多版本共存通过项目级隔离、环境约束和工具链适配实现：各项目独立声明 Hyperf/PHP 版本，禁用全局安装，启动时显式指定 PHP 路径，配置与迁移按版本语义管理，跨版本兼容依赖分阶段迁移和公共包抽象。
Hyperf 多版本共存不是靠“同时运行多个 Hyperf 版本”来实现的，而是通过项目级隔离 + 环境约束 + 工具链适配完成的。核心思路是：每个项目绑定明确的 Hyperf 版本、PHP 版本和依赖生态，避免跨项目污染。
按项目锁定版本，不混用全局安装
Hyperf 不提供类似 Node.js 的 nvm 式多版本管理工具，也不建议全局安装 hyperf/cli 或 bin/hyperf.php 到系统路径。正确做法是：
- 每个项目使用独立的 composer.json，严格声明
"hyperf/*": "2.2.*"或"hyperf/*": "3.0.*"等范围约束 - 升级前先确认当前项目是否满足目标版本的 PHP 要求（如 v3.x 需 PHP 8.1+，v2.x 支持 PHP 7.4–8.0）
- 避免在项目中执行
composer global require hyperf/devtool，改用本地安装：composer require --dev hyperf/devtool
PHP 多版本环境下的进程一致性保障
当服务器装了 PHP 8.0 和 PHP 8.1，而你的 Hyperf v2 项目需跑在 8.0、v3 项目需跑在 8.1 时，关键是要确保命令行启动、热重载、定时任务等子进程不“偷换”PHP 解释器：
- 启动服务时显式指定 PHP 路径：
/usr/bin/php8.0 bin/hyperf.php start或/usr/bin/php8.1 bin/hyperf.php start - 修改
server:watch行为：Hyperf 内部已推荐使用 PHP_BINARY 常量获取当前解释器路径，确保 watch 子进程与主进程 PHP 版本一致 - 在 Supervisor 或 systemd 配置中，明确写死
Environment=PATH=/usr/bin/php8.0/bin:/usr/local/bin类似路径，而非依赖默认 PATH
配置与迁移文件的版本感知设计
不同 Hyperf 版本对配置加载机制、数据库迁移命令、模型生成逻辑有差异，需主动适配：
- 迁移文件本身不带版本号，但命名需体现语义（如
2025_03_10_152000_add_status_to_orders_v3.php），配合 Git 提交信息说明适用版本 - v2.x 使用
php bin/hyperf.php migrate，v3.x 同样可用，但若含新特性（如基于 Attributes 的注解迁移），需确保hyperf/database组件也同步升级 - 敏感配置统一走
.env，不同版本项目各自维护.env.production或.env.v2，通过--env参数切换，避免配置逻辑耦合框架版本
代码兼容性过渡策略
跨大版本（如 v2 → v3）无法直连共存，但可分阶段降低迁移风险：
- 先在 v2 项目中引入
hyperf/code-generator，用它预生成 PHP 8 Attributes 结构，提前暴露注解转换问题 - 将公共逻辑（如 DTO、领域模型、基础 Service）抽成独立 Composer 包，通过版本约束控制兼容性（例如
"myorg/core": "^1.0"支持 v2/v3 共用） - v3 新增的类型增强（如
Result枚举、void返回类型）在 v2 项目中不启用，反之亦然；接口契约尽量保持数组/对象输入输出，减少框架强依赖
