必须安装 hyperf/http-server 才能启动 http 服务，骨架默认不包含该组件，缺失会导致 php bin/hyperf.php start 后无端口监听、curl 超时；安装后默认监听 0.0.0.0:9501，无需额外配置。
不装 hyperf/http-server 就启动不了 HTTP 服务
Hyperf 骨架项目默认不含 HTTP 服务组件，php bin/hyperf.php start 后进程看似运行，但实际没监听任何端口，curl http://127.0.0.1:9501 会直接超时。这不是配置问题，是根本没加载 HTTP 协议栈。
必须显式安装：
composer require hyperf/http-server- 安装后无需额外配置，默认启用
SERVER_HTTP类型服务，监听0.0.0.0:9501 - 若已启动过服务，需先
Ctrl+C终止再重试，否则新组件不会热加载
AutoController 的 prefix 别加尾部斜杠
写成 #[AutoController(prefix: '/api/')] 看似规范，但会导致所有路由多出一个 /，比如访问 /api/index 实际匹配的是 /api//index，404。
正确写法只有这一种：
-
#[AutoController(prefix: '/api')]—— 不带结尾斜杠 - 方法名自动转小写连字符路径，
index()→/api/index，getUserInfo()→/api/get-user-info - 如需精确控制路径，改用
#[Controller]+#[GetMapping]组合
验证路由是否生效，别只靠浏览器刷新
控制器文件保存后，Hyperf 不会自动重载路由定义（除非启用了 hyperf/watcher）。常见“写了控制器却 404”其实是路由没被扫描到。
最可靠验证方式是命令行检查：
-
php bin/hyperf.php route:list—— 查看已注册的全部路由，确认/api/xxx出现在列表中 - 若为空，检查：
app/Controller/下文件命名是否为*Controller.php、类是否在AppController命名空间、composer.json中的 autoload 是否包含"App\" - 临时测试可删掉
prefix，用#[AutoController]看能否命中/index，排除路径前缀干扰
端口被占、日志刷屏、启动卡住——三个高频阻塞点
刚跑通服务就遇到异常？大概率是这三类问题之一：
-
Address already in use：用lsof -i :9501（macOS/Linux）或netstat -ano | findstr :9501（Windows）查 PID，再kill -9 {pid}或任务管理器结束进程 - 日志太多看不清关键信息：注释掉
config/autoload/logger.php中的LogLevel::DEBUG和LogLevel::NOTICE，保留ERROR和INFO即可 - 启动后无响应、卡在某一行：检查
config/autoload/server.php里servers数组是否误删了http项，或type写成了Server::SERVER_BASE而非Server::SERVER_HTTP
四步只是骨架，真正卡住的地方往往在环境校验和路径细节上。特别是 prefix 少个斜杠、http-server 漏装、route:list 不验证——这三个动作不做，后面所有代码都白写。
