Hyperf入门需理清环境搭建、路由配置和服务启动三件事：确认PHP≥8.1、安装Swoole扩展、推荐Docker开发；用骨架创建项目并修改.env；支持配置文件与注解两种路由方式；理解协程、中间件洋葱模型及依赖注入机制。
Hyperf 入门不难，关键在理清三件事：环境搭得稳、路由写得对、服务跑得起来。它不是传统 PHP 框架，而是基于协程的高性能框架，所以别用 Laravel 思维去套——先接受“启动后常驻内存”这个前提，后面就顺了。
装好环境，一步都不能跳
Hyperf 对底层依赖明确，跳过检查容易卡在启动环节：
- 确认 PHP ≥ 8.1：
php -v，低于版本会报错或功能受限 - 必须装 Swoole 扩展：
pecl install swoole，然后在php.ini加extension=swoole.so，再用php --ri swoole验证是否生效 - 推荐用 Docker 开发（尤其 Windows 用户）：项目自带
docker-compose.yml和Dockerfile，直接docker-compose up -d就能拉起完整环境，省去本地扩展编译烦恼 - 别漏掉基础扩展：JSON、OpenSSL、PDO（连数据库时）、Redis（用缓存或队列时）都得启用
创建项目，从骨架开始
官方骨架已预置常用结构，不用自己从零搭：
- 执行命令：
composer create-project hyperf/hyperf-skeleton myapp - 进目录后，改
.env文件调整基本配置，比如：APP_NAME=api-demo-
SERVER_PORT=9501（避免端口被占） -
SWOOLE_HTTP_MODE=1（默认 HTTP 服务）
- 启动服务：
php bin/hyperf.php start，看到终端输出 Hyperf server started 即成功
写个接口，验证流程走通
别急着写业务，先让一个请求能返回内容：
- 方式一：配置文件路由（适合简单场景）
编辑config/routes.php：use Hyperf\HttpServer\Router\Router;<br>Router::get('/hello', function () {<br> return ['message' => 'Hello Hyperf'];<br>}); - 方式二：注解路由（更主流，利于维护）
新建app/Controller/HelloController.php：namespace App\Controller;<br>use Hyperf\HttpServer\Annotation\GetMapping;<br>use Hyperf\HttpServer\Annotation\Controller;<br><br>#[Controller]<br>class HelloController<br>{<br> #[GetMapping(path: '/hello')]<br> public function index()<br> {<br> return ['status' => 'ok'];<br> }<br>} - 访问
http://127.0.0.1:9501/hello，看到 JSON 响应，说明路由、控制器、响应链全通
理解核心机制，少踩坑
新手容易忽略但影响长期开发的点：
-
协程不是多线程：所有逻辑默认在协程中运行，不能用
sleep()或阻塞 IO；要用co::sleep()或异步客户端（如Hyperf\HttpClient） - 中间件是洋葱模型：请求进来→中间件A→B→控制器→B出→A出→响应，适合做鉴权、日志、跨域
-
依赖注入靠构造函数：控制器里要调服务？直接写
public function __construct(private UserService $service) {}，框架自动注入 -
配置可动态覆盖：环境变量（如
.env中的DB_HOST）会自动替换config/database.php里的占位符
