hyperf 安装需确保 php≥8.1、swoole/swow 引擎适配系统、必需扩展启用；推荐 docker 部署，macos 本地或 wsl2 开发；启动后需手动重启或装 watcher 热重载，禁用 xhprof 等不兼容扩展。
Hyperf 安装不是“装完就能跑”，环境配置不到位，项目大概率启动失败或运行异常。核心在于三点：PHP 版本达标、网络引擎就位、扩展兼容无冲突。
操作系统与网络引擎匹配关系
Hyperf 本身不直接限定操作系统，但所选网络引擎决定了实际支持范围：
- Swoole 引擎（推荐新手）：仅支持 Linux 和 macOS；Windows 用户必须借助 Docker 或 WSL2
- Swow 引擎 ：全平台支持（Windows/Linux/macOS），适合 Windows 原生开发，但社区资源和文档相对少一些
- macOS 用户注意：本地部署比 Docker 更快，Docker 共享磁盘机制会导致 Hyperf 启动明显变慢
PHP 及必需扩展要求
最低 PHP 版本为 8.1，建议使用 8.2 或 8.3。以下扩展必须启用：
- 基础类 ：json、openssl、pdo（连接数据库必需）
- 可选但常用 ：redis（缓存）、protobuf（gRPC）、pcntl（Swoole 进程控制，仅 Swoole 引擎需要）
- Swoole 特别设置 ：php.ini 中需添加
swoole.use_shortname = Off
开发环境推荐方案
不建议手动从零配环境，尤其对新手：
- Docker（最省心）：官方提供预构建镜像（如
hyperf/hyperf:8.1-alpine-v3.18-swoole），一键拉起，环境完全一致 - 本地原生（macOS/Linux 首选）：适合熟悉 PHP 扩展编译的用户，避免 Docker 文件系统开销
- WSL2（Windows 用户）：比 Docker for Windows 性能更稳，接近原生 Linux 体验
安装后关键注意事项
Hyperf 是常驻内存的 CLI 框架，行为和传统 PHP-FPM 完全不同：
- 修改代码后不会自动重载，必须 Ctrl+C 终止进程，再执行
php bin/hyperf.php start - 如需热重载，可安装
hyperf/watcher组件，运行php bin/hyperf.php server:watch - 禁用不兼容扩展：xhprof、blackfire、uopz、trace；xdebug 仅在 PHP ≥8.1 + Swoole ≥5.0.2 下可用
- 生产环境务必关闭 OPcache 的
opcache.validate_timestamps，否则代码更新不生效
