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

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

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

前言

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

环境要求

操作系统支持

Hyperf框架的运行环境取决于所使用的网络引擎：

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

对于Windows开发者，推荐使用Docker或WSL2作为开发环境。

软件依赖

基础环境要求：

• PHP ≥ 8.1版本
• Composer包管理工具

必须的PHP扩展：

• JSON扩展（核心依赖）
• OpenSSL扩展（HTTPS支持）
• PDO扩展（MySQL数据库支持）
• Redis扩展（Redis客户端支持）
• Protobuf扩展（gRPC服务支持）

网络引擎扩展（二选一）：

• Swoole ≥ 5.0（需关闭Short Name）
• Swow ≥ 1.4

安装方式

方式一：使用Composer创建项目

Hyperf提供了两种项目骨架：

1. 基于Swoole的项目骨架

composer create-project hyperf/hyperf-skeleton

2. 基于Swow的项目骨架

composer create-project hyperf/swow-skeleton

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

方式二：Docker环境开发

对于本地环境不符合要求的情况，推荐使用Docker：

1. 启动容器（以Alpine镜像为例）：

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

开发时修改代码后，需重启服务：

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

环境配置注意事项

性能优化建议

1. MacOS用户建议直接使用本地环境而非Docker，避免文件共享导致的性能下降
2. 生产环境建议关闭OPcache的验证时间戳选项

扩展兼容性问题

以下扩展与Hyperf存在兼容性问题，开发时应避免使用：

• 性能分析类：xhprof、blackfire
• 调试类：xdebug（PHP≥8.1且Swoole≥5.0.2时可用）
• 代码跟踪类：trace
• 运行时修改类：uopz

常见问题解决方案

1. Swoole安装问题：

   • 确保安装时添加--enable-swoole-json选项
   • 检查php.ini中swoole.use_shortname = Off

2. 权限问题：

   • Docker环境下添加--privileged -u root参数
   • Linux系统确保项目目录有足够权限

3. 端口冲突：

   • 检查9501端口是否被占用
   • 可在config/autoload/server.php中修改监听端口

结语

通过本文介绍的方法，开发者可以快速搭建Hyperf开发环境。建议初学者从Swoole引擎开始，待熟悉框架后再尝试Swow引擎。实际开发中，应根据项目需求选择合适的组件组合，以获得最佳性能表现。

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