Hyperf扩展包选择与安装技巧

Hyperf安装扩展包应按需启用、避免默认全选、优先用官方骨架起步；新手首次搭建直接回车采用默认配置最稳妥，不确定用途的组件选n更安全，后期按需composer require添加即可。

Hyperf 安装扩展包的核心原则是：按需启用、避免默认全选、优先用官方骨架默认配置起步。

安装时如何选择扩展包

执行 composer create-project hyperf/hyperf-skeleton 后，命令行会逐项提示是否安装各类组件（如 Redis、Async Queue、gRPC、JSON RPC 等）。关键操作建议如下：

• 新手首次搭建，全部直接回车——采用默认选项最稳妥，框架会自动适配基础依赖和配置
• 看到类似 [y] yes [n] None of the above 的提示时，若不确定用途（例如 hyperf/async-queue），选 n 更安全；后期需要再 composer require 添加即可
• 避免在安装阶段勾选未配置好中间件的组件（比如选了 Redis 队列但没配 redis.php），否则 php bin/hyperf.php start 可能直接报错退出
• Swow 用户请用 hyperf/swow-skeleton，它已预置 Swow 兼容配置，不建议在 Swoole 骨架里强行替换引擎

常用第三方包推荐与安装方式

Hyperf 生态中高频使用的扩展包，推荐按场景明确引入：

• Redis 支持：composer require hyperf/redis，自动发布 config/autoload/redis.php，填入连接参数即可使用 RedisFactory
• 异步队列：composer require hyperf/async-queue，搭配 Redis 或 Database 驱动，无需安装时一步到位，按业务节奏接入
• gRPC 通信：composer require hyperf/grpc + protoc 工具生成代码，服务端需启用 protobuf 扩展并关闭 Swoole shortname
• 数据库增强：composer require hyperf/database（已内置）+ 可选 hyperf/model-cache 提升查询性能
• 监控与可观测性：composer require hyperf/metric（Prometheus 指标）、hyperf/tracer（OpenTracing）

扩展安装常见避坑点

不是所有 PHP 扩展都兼容 Hyperf 协程环境，安装前务必确认：

• Swoole 引擎下必须关闭 swoole.use_shortname = Off（写入 php.ini），否则部分组件（如 Protobuf）可能初始化失败
• 生产环境禁用 xdebug、xhprof、uopz 等非协程安全扩展；开发调试可用 blackfire 替代
• Alpine 镜像中安装扩展（如 mongodb、zookeeper）需先 apk add build-base php-dev pcre-dev，再 pecl install 并手动写入 extension=xxx.so
• Windows 用户建议通过 WSL2 运行，而非原生 CMD 或 PowerShell；Docker for Windows 性能较差，Mac 用户也应优先本地环境

扩展不是越多越好，一个干净启动的 skeleton 比一堆半配置组件更利于快速验证逻辑。