hyperf 3.1 启动失败八成因缺失 hyperf/http-server 组件、swoole shortname 开启或 windows 原生运行；需手动安装 http-server、禁用 swoole.use_shortname 并在 linux/macos 或 docker 容器中运行。
Hyperf 3.1 跑不起来，八成是环境或骨架缺关键组件——不是版本不对，而是hyperf/http-server没装。
PHP 和 Swoole 版本必须匹配
Hyperf 3.1 明确要求 PHP ≥ 8.1、Swoole ≥ 5.0（且不能启用 shortname）。用 php -v 和 php --ri swoole 检查后，重点看两处：
-
swoole.version是否 ≥ 5.0 -
swow或shortname是否被启用（若输出里有shortname => On，需在php.ini中加swoole.use_shortname = Off并重启 PHP） - Ubuntu/Debian 用户注意：
php-swoole包通常不满足 Hyperf 3.1 要求，必须源码编译安装 Swoole 5.1+，否则启动时会报Class 'Swoole\Http\Server' not found
composer create-project 后必须手动装 http-server
官方骨架 hyperf/hyperf-skeleton 默认不含 HTTP 服务组件。跳过这步会导致 php bin/hyperf.php start 静默启动、无监听端口、curl http://127.0.0.1:9501 直接超时。
- 进入项目根目录后，立刻执行：
composer require hyperf/http-server - 不要用
composer install替代——它只装require-dev里的东西，而http-server是运行时必需依赖 - 装完检查
composer.json的require字段是否已含"hyperf/http-server": "^3.1"
注解路由 prefix 写法容易错
#[AutoController(prefix: '/api')] 是对的，#[AutoController(prefix: '/api/')] 是错的——末尾斜杠会导致实际访问路径变成 /api//index，404。
- Hyperf 的注解路由 prefix 是「前缀拼接」，不是「路径匹配前缀」
- 方法级路径（如
public function index()）会被自动映射为GET /，最终完整路径 =prefix + method path - 若控制器内定义了多个方法，建议统一用
#[GetMapping]等显式注解，避免隐式行为干扰调试
Windows 下别硬刚本地环境
Hyperf 官方不支持 Windows 原生运行（Swoole 在 Win 上不可用），所谓“能跑”基本是 Docker 模拟出来的。但 Docker for Windows 家庭版常因 WSL2 兼容性问题卡在 bin/hyperf.php start 不返回。
- 推荐方案：用
docker run -it -v $(pwd):/app -p 9501:9501 hyperf/hyperf:8.2-alpine-v3.16-swoole进入容器后，再cd /app && composer create-project hyperf/hyperf-skeleton . - 切忌在宿主机用
php bin/hyperf.php start—— 即使提示 “Server started”，也大概率只是协程调度器初始化成功，HTTP Server 根本没注册 - Mac 用户也建议关掉 Docker 文件共享，直接本地跑；Win 用户接受「开发在容器、调试用 VS Code Remote-Container」这个现实
真正卡住新手的从来不是语法，而是 http-server 缺失、Swoole shortname 开启、Windows 本地直跑这三件事——它们不会报明显错误，只会让服务「看起来启动了，实则没监听」。
