hyperf 3.x 不兼容 php 8.0 及以下版本，因依赖 php 8.1+ 的协程语法、attributes 注解及底层调度器，低版本会触发 fatal error 或静默失败；必须升级 php 至 8.1+，并确保 swoole ≥5.0 且协程启用、安装 hyperf/http-server 组件、使用协程安全 i/o 链路。
Hyperf 3.x 不兼容老旧 PHP 版本——PHP 8.0 及以下版本无法运行，强行部署只会触发 Fatal error: Uncaught Error: Call to undefined function HyperfCoroutinego() 或静默失败。这不是配置问题，是语言特性断层导致的硬性不兼容。
PHP 8.0 或更低版本根本不能跑 Hyperf 3.x
Hyperf 3.x 依赖 PHP 8.1+ 的原生协程语法（如 match、枚举、只读类）、#[Attribute] 注解系统和协程调度器底层支持。PHP 8.0 缺失这些能力，即使 composer install 成功，php bin/hyperf.php start 也会在初始化阶段崩溃或直接无响应。
-
php -v输出为8.0.x或更早？必须升级，没有绕过方案 - Ubuntu/Debian 用户别用
apt install php默认源——它大概率装的是 PHP 7.4 或 8.0；改用 ondrej/php PPA 源安装php8.1或php8.2 - Mac 用户用
brew install php@8.2，它自带完整扩展集，比手动编译更稳 - Windows 用户请放弃本地部署：Swoole 在 Windows 原生不可用，所谓“能启动”基本是 Docker 模拟出来的假象，且 WSL2 兼容性差，建议直接用
docker run -p 9501:9501 hyperf/hyperf:8.2-alpine-v3.19-swoole
Swoole ≥5.0 且必须启用协程
Hyperf 所有核心能力（HTTP Server、DB 连接池、协程 HttpClient）都建立在 Swoole 协程基础上。仅安装 Swoole 扩展不等于可用——php --ri swoole 必须显示 support coroutines: enabled，否则一切 I/O 操作都会阻塞。
- 系统包管理器安装的
php-swoole（如 Ubuntu 的apt install php-swoole）通常为旧版（4.x），且默认禁用协程；必须卸载：sudo apt remove php-swoole - 改用
pecl install swoole，安装过程中明确选择y启用协程支持 - 检查
php.ini：确认只有一行extension=swoole.so，且添加swoole.use_shortname = Off（Hyperf 3.1+ 强制要求） - 验证协程是否真可用：
php -r "Swoole\Runtime::enableCoroutine(); go(fn() => var_dump('ok'));"，输出ok才算过关
骨架项目缺 hyperf/http-server 是最常见“起不来”原因
官方骨架 hyperf/hyperf-skeleton 默认不含任何 Server 组件。跳过这步会导致 php bin/hyperf.php start 看似成功，实则监听端口为空，curl http://127.0.0.1:9501 直接超时——不是代码错，是框架根本没注册 HTTP Server。
- 创建项目后立刻执行：
cd my-api && composer require hyperf/http-server - 检查
composer.json的require字段是否已含"hyperf/http-server": "^3.1" - 控制器注解中
prefix写成'/api/'（末尾带斜杠）会导致实际路由变成/api//index，返回 404；正确写法是#[AutoController(prefix: '/api')] - 验证路由是否生效：运行
php bin/hyperf.php route:list，应看到类似GET | /api/index | App\Controller\IndexController::index的条目
异步队列、Redis、DB 连接池等组件依赖协程安全链路
Hyperf 的异步能力不是“开关式启用”，而是整条 I/O 链路必须协同。哪怕环境全对，只要某处用了非协程组件（如原生 PDO、phpredis、file_get_contents），任务就会卡死或超时。
- 数据库必须用
Hyperf\DbConnection（而非原生 PDO），且config/autoload/databases.php中driver设为mysql或pgsql，不是pdo_mysql - Redis 必须用
Hyperf\Redis\Redis，确保config/autoload/redis.php中pool配置正确，且host/port可连通 - 异步队列需显式注册消费者进程：
config/autoload/processes.php必须包含Hyperf\AsyncQueue\Process\ConsumerProcess::class，注解方式已被废弃 - 投递 Job 时禁止传入资源句柄对象（如
PDO实例、Redis实例），只允许基础类型（string、int、array）
真正卡住人的地方往往不在版本号本身，而在协程链路的完整性——PHP 8.2 + Swoole 5.1 + hyperf/http-server 全装齐了，但忘了关 swoole.use_shortname，或 DB 配置里写了 pdo_mysql，服务照样起不来。每一步都要用对应命令验证，而不是“看起来没报错”就认为 OK。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
