Hyperf安装时交互式选项必须谨慎选择：Database、Redis Client、RPC protocol、Config center一律选n；推荐保留hyperf/constants、hyperf/async-queue、hyperf/validation；安装后须验证swoole.use_shortname=Off、vendor/hyperf/framework存在、.env中HTTP_PORT配置正确。
Hyperf 安装时的组件选项不是“按需勾选”，而是直接决定项目骨架结构和后续扩展成本。选错不光是多装几个包，更可能导致启动失败、协程阻塞或配置冲突。
哪些选项必须关掉（尤其新手）
安装过程中遇到带 [y]/[n] 的交互式提问，以下几项建议一律按回车选 n：
-
Database (MySQL Client)：除非你立刻就要连 MySQL，否则先跳过。开了但没配config/autoload/db.php会导致php bin/hyperf.php start报Connection refused -
Redis Client：同理，hyperf/redis装了就得确保 Redis 服务可达，且redis.php配置正确；否则服务卡在启动阶段 -
RPC protocol（JSON RPC / gRPC）：微服务调度组件，本地开发单体应用完全用不到。一旦选了，会自动引入hyperf/service-governance等一整套依赖，配置文件变复杂，且默认监听 9504 端口，容易和 HTTP 冲突 -
Config center（Apollo/Nacos/ETCD）：配置中心组件对初学者属于“提前透支复杂度”。.env文件 +HYPERF_ENV就够用，加了反而要额外部署中间件
哪些选项可以放心开（推荐保留）
这些组件轻量、解耦好、不影响启动，且日常开发高频使用：
-
hyperf/constants：提供常量管理 + 错误码模板（ErrorCode.php），比硬编码字符串靠谱得多 -
hyperf/async-queue：基于 Redis 的异步队列，只要后面想发邮件、写日志、处理耗时任务，它就是最省心的起点 -
hyperf/validation：如果安装流程里没出现这行，手动补上composer require hyperf/validation。表单校验几乎每个 Controller 都要写，别自己重复造轮子
选完之后必须立刻验证的三件事
安装完成不代表能跑起来。执行前务必确认：
-
php --ini输出里没有swoole.use_shortname=On—— 这个必须关，否则php bin/hyperf.php start会报Class 'Swoole\Http\Server' not found -
vendor/hyperf/framework目录存在，且bin/hyperf.php可执行。如果只有vendor/autoload.php没有hyperf.php，说明create-project没走完，可能中途中断过 -
.env文件里至少有HTTP_PORT=9501，且端口没被占用。Windows 用户注意：Docker 容器内启动和宿主机启动是两套环境，别在 WSL 里启了又去浏览器访问localhost:9501却连不上
最常被忽略的是：安装时跳过的组件，后期不能靠 composer require 补全。比如漏了 hyperf/database，后面再 require hyperf/db-connection 会因生命周期加载顺序错乱导致 Db::query() 找不到连接实例。真要加，得用 php bin/hyperf.php vendor:publish 手动发布配置，并检查 dependencies 是否注入了对应 ConnectionInterface。
