Hyperf本地加载失败主因是环境与启动机制不匹配，须启用DEBUG模式、验证Swoole协程就绪、禁用注解缓存并检查路径配置，Docker场景需查看容器日志及状态。
在本地开发 Hyperf 时，框架加载失败往往不报明确错误，只显示空白页、500 或直接退出，尤其在 Windows 下更常见。根本原因不是代码写错，而是环境配置与框架启动机制不匹配。要真正“看到错误”，关键不是改代码，而是让 Hyperf 在可调试的上下文中运行，并暴露底层问题。
启用详细错误报告并强制 CLI 启动
Hyperf 默认在生产模式下隐藏错误，即使本地开发也要手动激活调试通道：
- 确保 APP_ENV=dev 和 DEBUG=true 已写入
.env文件（不是系统环境变量，避免被覆盖） - 启动必须用
php bin/hyperf.php start—— 这是唯一进入 Swoole 协程环境的方式；php -S或 Apache 直接跑会跳过所有协程初始化，导致注解扫描、DI 容器等全部失效 - 启动前加环境变量：在终端执行
export HYPERF_DEBUG=1 && php bin/hyperf.php start（Linux/macOS）或set HYPERF_DEBUG=1 && php bin/hyperf.php start（Windows CMD），可触发更底层的日志输出
检查 Swoole 协程是否真实就绪
很多“加载失败”其实是 Swoole 没启用协程，Hyperf 启动后立即静默退出。别信 php --ri swoole 的表面输出：
- 运行
php --ri swoole | findstr "coroutine"（Windows）或php --ri swoole | grep coroutine（macOS/Linux），确认输出为 support coroutines => enabled，且版本 ≥ 5.1.0 - 检查
php.ini中是否设置了swoole.use_shortname = 0—— 不关这个，注解扫描器会因函数名冲突而跳过控制器类，不报错但路由全 404 - 若用 Docker，不要依赖镜像自带 PHP 版本；优先拉取官方
hyperf/hyperf:8.2-alpine-v3.22-swoole-slim-v6.1.6这类已验证协程开启的镜像
绕过注解缓存快速验证加载链
修改了控制器或配置却没生效？大概率是注解缓存未刷新，掩盖了真实加载问题：
- 打开
config/autoload/annotations.php，把'cacheable' => true改成 false - 删掉
runtime/container和runtime/cache目录（Hyperf 会自动重建） - 重启服务后，如果仍 404，说明注解路径配置错误；检查
'paths' => ['app/Controller']是否匹配你实际的控制器目录结构（注意大小写和 PSR-4 命名）
查看启动日志与容器内状态（Docker 场景）
用 Docker Desktop 运行时，错误常藏在容器后台：
- 启动容器后立刻执行
docker logs -f my-hyperf-app，观察第一屏输出 —— 出现Segmentation fault是扩展版本不兼容，出现Class not found是 Composer 自动加载失败 - 若容器秒退，运行
docker inspect my-hyperf-app | jq '.[0].State.Status'看退出码；非 0 表示启动命令崩溃，重点检查-w /var/www/html工作目录是否正确、bin/hyperf.php文件是否存在且有执行权限 - 进容器调试：
docker exec -it my-hyperf-app sh，然后手动执行php bin/hyperf.php start，错误会直接打印到终端
