Hyperf新手怎么入门_Hyperf初学者快速上手指南【教程】

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 HyperfHttpServerRouterRouter;<br>Router::get('/hello', function () {<br>    return ['message' => 'Hello Hyperf'];<br>});

• 方式二：注解路由（更主流，利于维护）
  新建 app/Controller/HelloController.php：

  namespace AppController;<br>use HyperfHttpServerAnnotationGetMapping;<br>use HyperfHttpServerAnnotationController;<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() 或异步客户端（如 HyperfHttpClient）
• 中间件是洋葱模型：请求进来→中间件A→B→控制器→B出→A出→响应，适合做鉴权、日志、跨域
• 依赖注入靠构造函数：控制器里要调服务？直接写 public function __construct(private UserService $service) {}，框架自动注入
• 配置可动态覆盖：环境变量（如 .env 中的 DB_HOST）会自动替换 config/database.php 里的占位符