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

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

hyperf 🚀 A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease. 项目地址: https://gitcode.com/gh_mirrors/hy/hyperf

前言

Hyperf是一款高性能的企业级PHP协程框架，专为微服务和中间件开发而设计。本文将详细介绍如何在不同环境下安装和配置Hyperf框架，帮助开发者快速搭建开发环境。

环境要求

操作系统支持

Hyperf框架对操作系统有以下要求：

1. 使用Swoole网络引擎时：仅支持Linux和MacOS系统
2. 使用Swow网络引擎时：支持Windows、Linux和MacOS全平台

对于Windows开发者，推荐使用Docker for Windows作为开发环境，以避免原生环境下的兼容性问题。

PHP版本要求

Hyperf要求PHP版本至少为8.1，这是为了充分利用PHP最新特性和性能优化。

必备扩展

以下是运行Hyperf必须安装的PHP扩展：

• 网络引擎扩展（二选一）：
  • Swoole（≥5.0版本）且需关闭Short Name
  • Swow（≥1.4版本）
• JSON扩展（PHP内置）
• Pcntl扩展（仅Swoole引擎需要）
• OpenSSL扩展（如需HTTPS支持）
• PDO扩展（如需MySQL支持）
• Redis扩展（如需Redis客户端支持）
• Protobuf扩展（如需gRPC服务支持）

安装方式

1. 使用Composer创建项目

Hyperf推荐使用Composer作为依赖管理工具。安装前请确保已正确安装Composer。

创建Swoole驱动项目

composer create-project hyperf/hyperf-skeleton

创建Swow驱动项目

composer create-project hyperf/swow-skeleton

安装过程中会提示选择需要的组件，初学者可直接按回车使用默认选项。

2. Docker环境开发

对于本地环境不满足要求或希望快速搭建环境的开发者，可以使用Docker方案。

启动容器

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

在容器内创建项目

composer create-project hyperf/hyperf-skeleton

启动项目

cd hyperf-skeleton
php bin/hyperf.php start

项目启动后，可在宿主机的映射目录中查看和修改代码。修改后需重启服务：

1. 使用CTRL+C终止当前进程
2. 重新执行php bin/hyperf.php start

兼容性注意事项

由于Hyperf基于协程实现，与部分PHP扩展存在兼容性问题，以下扩展不建议同时使用：

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

环境选择建议

1. Mac用户：推荐本地环境直接安装，避免Docker共享磁盘导致的性能问题
2. Windows用户：必须使用Docker方案
3. Linux用户：可根据实际情况选择本地或Docker方案

常见问题解决

1. 安装速度慢：可使用国内Composer镜像源
2. 服务无法启动：检查是否安装了所有必需扩展，特别是Swoole/Swow扩展
3. 协程冲突：确保没有加载不兼容的扩展

通过以上步骤，您应该已经成功搭建了Hyperf开发环境。接下来可以开始探索Hyperf提供的各种强大功能，如依赖注入、AOP、微服务支持等特性。

hyperf 🚀 A coroutine framework that focuses on hyperspeed and flexibility. Building microservice or middleware with ease. 项目地址: https://gitcode.com/gh_mirrors/hy/hyperf