启动成功但访问不到首页，90%是请求未进入框架，需先确认服务运行、端口通畅、curl地址准确，再检查注解扫描路径、cacheable配置及runtime残留文件。
启动成功但访问不到首页，90% 是请求没走到框架里，而不是代码或路由写错了。先确认服务真在跑、端口真通、请求真发到了正确地址，再查框架内部逻辑。
检查终端是否真输出了监听日志
执行 php bin/hyperf.php start 后，必须看到类似这样的行：
[INFO] Hyperf\HttpServer\Server: HTTP server listening at http://0.0.0.0:9501
如果没有，说明服务根本没起来。常见原因包括：
-
swoole.use_shortname = Off没写进php.ini，报错信息里通常含undefined function swoole_http_server - PHP 版本低于 8.0（Hyperf v3.x 要求），
php -v必须确认 -
runtime/或storage/目录权限不对，进程用户（如www-data）无法写入，错误日志里会出现Permission denied和具体路径 - 端口被占，但没报错——有些旧版 Swoole 会静默失败，用
netstat -tuln | grep :9501主动查一遍更可靠
确认 curl 访问地址与监听地址严格一致
Hyperf 默认监听 0.0.0.0:9501，但浏览器访问 http://127.0.0.1:9501 不等于一定通。必须用 curl 验证：
- 执行
curl -v http://127.0.0.1:9501/，看返回是Connection refused（端口不通）、404（框架收到但没匹配路由）、还是空响应（框架崩溃） - 如果用 Docker，宿主机访问地址不是
:9501，而是docker-compose.yml中ports映射的左边端口，比如- "8080:9501"，就得访问http://127.0.0.1:8080/ - Windows 下若用 WSL2，
localhost可能解析不到，改用http://127.0.0.1:9501或http://$(hostname -I | awk '{print $1}'):9501
验证默认路由是否真被加载
Hyperf v3.x 的 skeleton 默认首页由 App\Controller\IndexController::index() 响应，靠注解 #[GetMapping("/")] 注册。它不生效的主因是注解没扫描到：
- 确认控制器文件在
app/Controller/IndexController.php，命名空间是App\Controller，且顶部有use Hyperf\HttpServer\Annotation\GetMapping; - 检查
config/autoload/annotations.php中'paths' => ['app/Controller']是否存在，路径必须和实际目录名完全一致（区分大小写） - 开发环境务必设
'cacheable' => false，否则改了注解不重启服务就无效 - 别用
php bin/hyperf.php start启动后手动改代码——用php bin/hyperf.php server:watch，它会自动 reload 并打印扫描到的路由列表
留意 runtime 下残留只读文件导致静默失败
哪怕前面都对了，runtime/container/ 或 runtime/proxy/ 下若有 root 创建的只读文件，Swoole 进程（如 www-data）仍会因无法覆盖而启动失败，但终端可能只显示空白或卡住。
处理步骤必须按顺序：
- 停服务：
php bin/hyperf.php stop或killall -9 php - 清空 runtime：
sudo -u www-data rm -rf runtime/*（必须用进程用户执行） - 再启动：
php bin/hyperf.php start
这个动作看起来像“重启”，实则是清除协程环境下不可复用的旧状态——很多看似玄学的 404，根源就在这里。
