hyperf 3.x 要求 php ≥8.1 且 swoole ≥5.0，否则启动失败或注解失效；需验证 php -v、php --ri swoole、协程启用状态、http-server 组件安装、注解扫描路径及 opcache.enable_cli=0 配置。
Hyperf 3.x 要求 PHP ≥8.1、Swoole ≥5.0，低于任一版本都会导致启动失败或注解失效——不是报错就是静默不工作。
php -v 显示 8.0.x 或更低？必须升级
Hyperf 3.x 已彻底放弃对 PHP 8.0 及以下版本的支持。即使 composer install 成功，运行 php bin/hyperf.php start 时会直接抛出 Fatal error: Uncaught Error: Call to undefined function HyperfCoroutinego() 类似错误，本质是协程语法（如 match 表达式、枚举、只读类）在低版本不可用。
- Ubuntu/Debian 用户优先用 ondrej/php PPA 源安装 PHP 8.1+，避免源码编译带来的扩展缺失
- 确认
php -i | grep 'PHP Version'输出为8.1.x或更高，且php --ri swoole中Version => 5.0.x或5.1.x - 别信“只差小版本”，
8.0.30和8.1.0之间存在 ABI 不兼容，Hyperf 的 DI 容器和注解扫描器会崩溃
pecl install swoole 后 php --ri swoole 显示 coroutine => disabled
Swoole 编译时未启用协程支持，常见于用系统包管理器（如 apt install php-swoole）安装的旧版扩展。Hyperf 所有核心能力（HTTP Server、DB 连接池、Guzzle 协程客户端）都依赖 coroutine => enabled。
- 必须卸载系统自带 swoole：
sudo apt remove php-swoole（Ubuntu）或brew uninstall php-swoole（macOS） - 改用
pecl install swoole，安装过程中会提示是否启用 coroutines —— 选y - 检查
php.ini是否重复加载：搜索是否有多个extension=swoole.so行，保留唯一一行即可 - 关键验证命令：
php -r "echo SwooleCoroutine::create(fn() => var_dump('ok')) ? 'ok' : 'fail';"，输出ok才算真正可用
composer require hyperf/http-server 后 php bin/hyperf.php start 无监听端口
这不是代码问题，而是 Hyperf 3.x 的组件自动发现机制被破坏：缺少 hyperf/http-server 时，框架根本不会注册 HTTP Server，start 命令看似成功，实则什么也没监听。
- 骨架项目默认不含任何 Server 组件，
composer create-project hyperf/hyperf-skeleton只是空壳 - 必须显式安装：
composer require hyperf/http-server，且确保安装后vendor/hyperf/http-server目录存在 - 若已安装但无效，执行
composer dump-autoload -o强制刷新自动加载，并确认config/autoload/server.php中'type' => 'http'的 server 配置未被注释或覆盖 - 启动后用
lsof -i :9501（Linux/macOS）或netstat -ano | findstr :9501（Windows WSL）验证端口是否真被占用
config/autoload/annotations.php 里 scan 目录漏配 app/Controller
控制器加了 #[AutoController] 却始终 404，php bin/hyperf.php route:list 为空，大概率是注解扫描路径没覆盖到控制器目录。
- Hyperf 默认只扫描
app下的Controller、Service、Model，但如果你把控制器放在app/Http/Controller或自定义命名空间下，必须手动加进scan['paths'] - 检查
config/autoload/annotations.php中是否包含'app/Controller'，注意路径是相对BASE_PATH（即项目根目录），不是绝对路径 - 别写成
'App/Controller'或'app\Controller'，Linux 系统下大小写敏感，反斜杠会被当转义符处理 - 修改后必须重启服务——Hyperf 的注解扫描只在进程启动时做一次，热重载不触发重新扫描
最常被忽略的是 opcache.enable_cli=1 这个配置：它会让 CLI 模式下的注解反射失效，导致所有 #[AutoController]、#[GetMapping] 全部被跳过，且不报错。务必在 php.ini 中设为 opcache.enable_cli=0。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
