hyperf 在 macos 上可直接通过 composer 或 docker 安装，需 php ≥ 8.1、swoole ≥ 5.0 且禁用 short name，推荐 homebrew 管理环境；m1/m2/m3 用户优先使用 brew install php@8.2 swoole。
在 macOS 上安装 Hyperf 框架本身不涉及“系统级部署”，而是本地 PHP 开发环境下的项目搭建。Hyperf 是一个基于 Swoole 或 Swow 的高性能 PHP 协程框架，它原生支持 macOS（包括 Intel 和 Apple Silicon M1/M2/M3），无需虚拟机或黑苹果方案。只要你的 Mac 已具备兼容的 PHP 环境，安装过程直接、轻量。
✅ 前置环境检查与准备
Hyperf 要求明确且严格，缺一不可：
-
PHP 版本 ≥ 8.1（官方强制要求，7.4/8.0 已不支持）；执行
php -v确认 -
Swoole 扩展 ≥ 5.0，且必须关闭
short name（即禁用swoole.use_shortname=Off） -
必备 PHP 扩展：
json、openssl、pdo、redis、protobuf（如用 gRPC） - 推荐使用 Homebrew + php@8.1 或 php@8.2 安装 PHP 及扩展，避免系统自带低版本 PHP
? 两种主流安装方式（任选其一）
方式一：本地 Composer 直装（推荐 macOS 用户）
- 确保已安装最新版
composer（curl -sS https://getcomposer.org/installer | php） - 运行命令创建项目：
composer create-project hyperf/hyperf-skeleton myapp - 进入目录并启动：
cd myapp && php bin/hyperf.php start - 访问
http://127.0.0.1:9501，看到{"method":"GET","message":"Hello Hyperf."}即成功
方式二：Docker 容器化（适合隔离环境或快速验证）
Hyperf 3.2.3
下载
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
- 安装 Docker Desktop for Mac（Apple Silicon 用户请选 ARM64 镜像）
- 拉取并运行官方镜像：
docker run -it --rm -v $(pwd)/myapp:/data/project -p 9501:9501 hyperf/hyperf:8.2-alpine-v3.19-swoole - 在容器内执行：
composer create-project hyperf/hyperf-skeleton . && php bin/hyperf.php start - 注意：Docker 共享文件系统在 macOS 上性能较差，仅建议用于测试或 CI 场景，非主力开发
⚠️ 常见问题与绕过要点
Mac 用户高频踩坑点：
-
M1/M2/M3 芯片编译 Swoole 失败？ 优先用 Homebrew 安装：
brew install php@8.2 swoole，自动适配 ARM 架构 -
报错 “swoole.use_shortname must be Off”？ 编辑
php.ini（用php --ini查路径），添加：swoole.use_shortname = Off -
启动后无法访问 9501 端口？ 检查是否被其他服务占用，或临时关闭防火墙：
sudo pfctl -d（macOS 默认启用） -
Redis/MySQL 连接失败？ 不要在容器里连宿主
127.0.0.1，改用host.docker.internal（Docker Desktop 支持）或本地服务直连
? 后续建议
项目初始化后，可立即启用常用组件：
- 数据库支持：
composer require hyperf/db-connection - Redis 客户端：
composer require hyperf/redis - API 文档：
composer require hyperf/swagger - 开发调试：
composer require hyperf/watcher --dev，启用热重载
Hyperf 在 macOS 上运行稳定、启动快、协程调度高效，是本地 PHP 高并发开发的理想选择。不需要折腾虚拟机、黑苹果或 OpenCore 引导——那些属于 macOS 系统安装范畴，和 Hyperf 无关。
