Hyperf入门指南与快速上手教程

这是一份专为新手打造的Hyperf高效入门指南，直击环境搭建、路由配置与服务启动三大核心环节，手把手教你避开常见陷阱：从确认PHP≥8.1、正确安装Swoole扩展、推荐Docker一键开发，到用骨架快速创建项目、灵活选择配置文件或注解方式定义路由，再到通过一个简单接口验证全流程畅通；更关键的是帮你破除Laravel思维定式，真正理解协程非阻塞、中间件洋葱模型、构造函数依赖注入等底层机制——掌握这些，你就能稳稳迈出高性能PHP协程开发的第一步。

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

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

  namespace App\Controller;
  use Hyperf\HttpServer\Annotation\GetMapping;
  use Hyperf\HttpServer\Annotation\Controller;
  
  #[Controller]
  class HelloController
  {
      #[GetMapping(path: '/hello')]
      public function index()
      {
          return ['status' => 'ok'];
      }
  }

• 访问 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 里的占位符

今天关于《Hyperf入门指南与快速上手教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于Hyperf的内容请关注golang学习网公众号！