必须用 composer create-project hyperf/hyperf-skeleton，其他方式大概率启动失败；因其预置必需组件、锁定兼容 swoole 版本（如 v3.1.x 对应 4.8+），并自动执行 build 脚本生成容器与代理类，跳过则导致 class not found 或协程阻塞。
必须用 composer create-project hyperf/hyperf-skeleton，其他方式大概率启动失败。 直接 composer require hyperf/hyperf 会拉取 dev-main 或高版本，而它们默认依赖 Swoole 5.0+，但你本地 CLI 环境很可能只装了 4.8 —— 这是 90% 启动报错的根源。
为什么 create-project 是唯一可靠入口
官方只维护 hyperf-skeleton 这个最小可运行骨架，它预置了 hyperf/framework、hyperf/server、hyperf/config 等必需包，并锁定了兼容的 Swoole 版本（如 v3.1.x 对应 Swoole 4.8+）。跳过它直接 require，等于跳过所有环境校验和依赖对齐。
- 别手动生成
composer.json再composer install—— 极易漏掉psr/container版本约束或 autoload 配置，导致bin/hyperf.php找不到ContainerInterface - 执行后立刻进目录跑
php bin/hyperf.php start，看到Swoole http server started才算真正通了 - 若卡在依赖解析，先确认 PHP ≥ 8.1（
php -v）、Swoole 已启用（php -m | grep swoole）
php bin/hyperf.php start 报 Class 'Swoole\Http\Server' not found 怎么办
这不是 Hyperf 的问题，而是 PHP CLI 环境没加载 Swoole 扩展，或版本不匹配。Hyperf v3.x 要求 Swoole ≥ 4.8.0，且必须启用 sockets 和 openssl。
- 运行
php --ri swoole，检查输出里Version行是否 ≥ 4.8.0；没有就重装：pecl install swoole（自动适配当前 PHP） - 确认
php.ini中有extension=swoole.so，且该文件被 CLI 加载（php -i | grep 'Loaded Configuration File'） - 检查
disable_functions是否禁用了pcntl_fork、exec等 —— Hyperf 启动时要用到它们
装完跑不通？先盯住这三个配置点
新项目默认配置往往不适用于本地开发环境，尤其在 Docker、WSL 或防火墙开启时。
-
.env里确保APP_ENV=dev，否则错误堆栈不显示；同时设SWOOLE_HTTP_HOST=0.0.0.0（不是127.0.0.1），否则可能连不上 -
config/autoload/annotations.php中'scan' => ['paths' => ['app']]必须启用，否则@GetMapping注解完全不生效 - Windows 用户若用 CMD 运行，必须写
php bin/hyperf.php start，不能直接bin/hyperf.php start（缺少 shebang 解析）
Hyperf 的“高性能”不是靠命令一键达成的，它依赖 PHP 版本、Swoole 扩展、autoload 映射三者严丝合缝。任何一环松动，都会在 start 时暴露——最常被忽略的是 CLI 环境和 Web 环境的 php.ini 不一致，以及 vendor/autoload.php 被意外破坏。
