新手跑通Hyperf路由的关键是四步：确认PHP≥8.1、Swoole≥5.0并启用；安装hyperf/http-server组件；用注解或routes.php注册路由并route:list验证；排查404时优先检查进程、端口监听及路由注册与命名空间是否正确。
Hyperf 路由处理对新手来说，关键不是记全所有写法，而是跑通一条最简路径：环境能跑、路由能注册、请求能响应。下面四步是真正卡住初学者的实操要点，按顺序做基本不会卡住。
确认运行环境和基础组件已就位
Hyperf 3.x 强制要求 PHP ≥ 8.1、Swoole ≥ 5.0。执行 php -v 和 php --ri swoole 验证。若 Swoole 未启用，需在 php.ini 中添加 extension=swoole.so。骨架项目默认不含 HTTP 服务组件，必须手动安装：
composer require hyperf/http-server —— 缺少这步，php bin/hyperf.php start 后无端口监听，curl 必然超时。
选一种路由方式并立即验证
新手建议从注解路由起步，代码更集中、改动反馈快：
- 在 app/Controller 下新建
IndexController.php，内容含#[AutoController(prefix: '/api')]注解 -
prefix 值必须以 / 开头、不以 / 结尾（例如写
/api，不能写/api/） - 保存后运行 php bin/hyperf.php route:list，检查输出中是否出现
GET | /api/index | App\Controller\IndexController::index - 若没出现，检查 config/autoload/annotations.php 是否启用了
'scan' => true，且'paths'包含app/Controller
用配置文件方式作为补充或替代
如果注解不生效或想更明确控制路由，直接改 config/routes.php：
- 使用
Router::get('/hello', [\App\Controller\IndexController::class, 'index'])这类写法，无需注解扫描 - 支持分组：
Router::group(['prefix' => '/api'], function () { ... }) - 可直接绑定中间件：
Router::get('/user', [...], ['middleware' => [AuthMiddleware::class]]) - 该文件修改后无需重启服务，下次请求自动生效（开发模式下）
快速定位常见失败原因
请求返回 404 或连接拒绝，优先查这三项：
-
服务没真启动：执行
ps aux | grep hyperf看进程是否存在；netstat -tuln | grep 9501看端口是否监听 -
路由没注册成功：运行
php bin/hyperf.php route:list是唯一权威依据，别凭感觉猜 -
控制器路径或命名空间错：比如文件放在
app/Controllers（多了一个 s），或命名空间写成App\Controllers（应为App\Controller）
