Hyperf 需 PHP 8.0+、启用 swoole/openssl/json/mbstring/curl 扩展且无 disable_functions 限制；创建项目应指定稳定版本并配置 .env 与 dev.php 启用调试，启动前务必验证基础响应。
Hyperf 不是靠 composer create-project 一键生成就能跑起来的“开箱即用”框架——它依赖 PHP 8.0+、Swoole 扩展、以及明确的扩展启用状态，缺一不可。直接运行安装命令却启动失败，90% 是卡在环境校验或扩展加载上。
检查 PHP 版本和必需扩展是否就位
Hyperf 3.x 要求 PHP ≥ 8.0，且必须启用 swoole、openssl、json、mbstring、curl。仅装了 Swoole 扩展但没启用（比如被 disable_functions 拦截），也会导致 php bin/hyperf.php start 报 Class 'Swoole\Http\Server' not found。
- 运行
php -v确认版本 ≥ 8.0 - 运行
php -m | grep swoole看是否列出；若无，需编译安装或通过pecl install swoole（注意匹配 PHP 版本） - 运行
php --ri swoole查看输出中support async_redis => enabled等关键项是否为enabled，不是则需检查php.ini中是否漏加extension=swoole.so -
disable_functions若包含pcntl_fork、exec等，会阻止 Hyperf 启动时的进程管理，务必移除
用 composer create-project 创建项目时的关键参数
官方推荐命令是 composer create-project hyperf/hyperf-skeleton，但它默认拉取最新稳定版（可能含 breaking change）。生产环境建议锁死版本，避免因 minor 升级引发协程上下文或注解解析异常。
- 指定版本：如
composer create-project hyperf/hyperf-skeleton:3.1.25（查最新 patch 版见 GitHub Releases） - 跳过脚本执行（防权限/路径问题）：
--no-scripts，后续手动运行php bin/hyperf.php start更可控 - 若 Composer 镜像慢或报
file could not be downloaded，先执行composer config -g repo.packagist composer https://packagist.phpcomposer.com切换国内镜像（注意：PHP Composer 官方镜像已停用，推荐阿里云或腾讯云镜像）
启动前必须改的两个配置文件
新项目默认监听 0.0.0.0:9501，但开发机若开了防火墙或 Docker 网络隔离，会连不上；同时 APP_ENV=dev 下未开启调试模式，报错不显示堆栈。
- 修改
.env：确保APP_ENV=dev且SWOOLE_HTTP_HOST=0.0.0.0、SWOOLE_HTTP_PORT=9501（非 127.0.0.1，否则容器外无法访问） - 修改
config/autoload/dev.php：把'debug' => false改成true，否则 500 错误只返回空白页 - 若用 Docker，还需确认
docker run -p 9501:9501映射正确，且容器内php进程能读取/proc/sys/net/core/somaxconn（Swoole 启动需该值 ≥ 511）
Hyperf 的“高性能”建立在 Swoole 协程 + 自动依赖注入 + 注解扫描之上，但这也意味着：任何阻塞操作（如未用 Co::sleep() 替代 sleep()）、或注解写错位置（比如 @Controller 加在普通类而非 App\Controller 下），都会让服务静默失败——这类问题不会报错，只会让接口无响应。动手前先跑通 curl http://127.0.0.1:9501 返回 “Hello Hyperf” 再加业务逻辑，比急着写微服务更省时间。
