Hyperf框架安装指南：从环境准备到项目创建

Hyperf框架安装指南：从环境准备到项目创建

hyperf 项目地址: https://gitcode.com/gh_mirrors/hyp/hyperf

环境要求详解

Hyperf作为一款高性能PHP协程框架，对运行环境有特定要求。根据您选择的网络引擎不同，环境需求也会有所差异。

操作系统兼容性

• Swoole引擎：仅支持Linux和MacOS系统
• Swow引擎：支持Windows、Linux和MacOS全平台

对于Windows开发者，虽然Swoole不支持原生运行，但可以通过Docker for Windows获得完整的开发体验。值得注意的是，MacOS环境下推荐本地直接运行，避免Docker共享磁盘导致的性能问题。

PHP版本要求

必须使用PHP 8.1或更高版本，这是Hyperf框架的基础要求。

必备扩展

无论选择哪种网络引擎，以下扩展都是必需的：

1. JSON扩展：用于数据序列化
2. OpenSSL扩展：HTTPS支持
3. PDO扩展：数据库操作
4. Redis扩展：Redis客户端支持
5. Protobuf扩展：gRPC服务支持

引擎特定要求

Swoole引擎：

• Swoole扩展版本≥5.0
• 必须关闭Short Name功能
• 需要Pcntl扩展支持

Swow引擎：

• Swow扩展版本≥1.4

安装方式选择

推荐方案：Composer创建项目

Hyperf通过Composer管理依赖，安装前请确保已安装最新版Composer。

Swoole项目创建

composer create-project hyperf/hyperf-skeleton

Swow项目创建

composer create-project hyperf/swow-skeleton

安装过程中会提示选择组件，初学者可直接按回车使用默认配置。项目骨架包含了常用组件和基础配置，可快速投入业务开发。

Docker开发方案

对于环境配置不熟悉或本地环境不满足要求的开发者，推荐使用Docker方案：

1. 启动容器（示例使用Swoole镜像）：

docker run --name hyperf \
-v /本地路径:/data/project \
-w /data/project \
-p 9501:9501 -it \
--privileged -u root \
--entrypoint /bin/sh \
hyperf/hyperf:8.1-alpine-v3.18-swoole

2. 在容器内创建项目：

composer create-project hyperf/hyperf-skeleton

3. 启动开发服务器：

cd hyperf-skeleton
php bin/hyperf.php start

开发过程中修改代码后，需重启服务：先按Ctrl+C停止，再重新执行启动命令。

扩展兼容性注意事项

由于Hyperf基于协程实现，与部分PHP扩展存在兼容性问题，特别是以下扩展：

• xhprof
• xdebug（PHP≥8.1且Swoole≥5.0.2时可用）
• blackfire
• trace
• uopz

开发时应避免加载这些扩展，以免造成不可预知的问题。对于调试需求，建议使用Hyperf内置的调试工具替代。

通过以上步骤，您应该已经成功搭建了Hyperf开发环境。接下来可以开始探索Hyperf提供的各种强大功能，构建高性能的PHP应用。

hyperf 项目地址: https://gitcode.com/gh_mirrors/hyp/hyperf