hyperf 是 php 微服务框架，非操作系统或安装包；需在 ubuntu 上按三步搭建：①换源安装 php 8.2+ 及扩展；②用 pecl 安装 swoole 5.0+ 并启用协程、禁用 opcache.enable_cli；③用 composer 创建项目、生成 di 代理类后启动。
Hyperf 不是操作系统，也不是能“一键安装”的软件包，它是一个 PHP 微服务框架，必须在已有的 Ubuntu 系统上配好运行环境才能启动。所谓“光速搭建”，核心是跳过误区、直击关键三步：装对 PHP + 装稳 Swoole + 创建项目不踩坑。下面按真实操作顺序讲清楚。
确认并安装 PHP 8.1+（别用系统默认旧版）
Ubuntu 自带的 PHP 版本通常太老（比如 8.1 以下），Hyperf 3.x 明确要求 PHP ≥ 8.1。直接 apt install php 默认装不上——得换源：
- 执行 sudo add-apt-repository ppa:ondrej/php && sudo apt update，引入 Ondřej 的权威 PHP 源
- 安装 PHP 8.2 CLI 及必需扩展：sudo apt install -y php8.2-cli php8.2-mbstring php8.2-bcmath php8.2-xml php8.2-zip php8.2-curl php8.2-gd php8.2-sockets
- 验证：php -v 应输出类似 PHP 8.2.x；php -m | grep mbstring 确保基础扩展已加载
安装并启用 Swoole 5.0+（Hyperf 的发动机）
Swoole 是 Hyperf 跑起来的底层支撑，只装扩展还不够，必须确认协程已开启、CLI 下 opcache 已关：
- 先装编译依赖：sudo apt install -y php8.2-dev gcc make
- 用 pecl 安装最新稳定版：sudo pecl install swoole（过程中按回车接受默认路径）
- 找到 swoole.so 路径：sudo find /usr -name "swoole.so" 2>/dev/null，常见如 /usr/lib/php/20220829/swoole.so
- 编辑 php.ini：sudo nano /etc/php/8.2/cli/php.ini，末尾加一行：extension=/usr/lib/php/20220829/swoole.so（⚠️务必写绝对路径，别只写 extension=swoole）
- 关闭 CLI 模式 opcache：opcache.enable_cli=0 这一行必须存在且为 0（搜索不到就手动加）
- 验证：php --ri swoole 看到 coroutine => enabled 和 Version => 5.1.x 才算成功
创建并启动项目（30 秒内跑通）
不用下载 ISO、不用改内核、不用配 Docker——Composer 一条命令生成骨架，启动前做两个小动作防报错：
- 确保 Composer 已安装（推荐 2.5+）：curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
- 创建项目：composer create-project hyperf/hyperf-skeleton myapp（过程中问是否删 .git 历史，输 y 回车）
- 进目录：cd myapp
- 生成 DI 代理类（避免 Class not found）：php bin/hyperf.php di:generate
- 启动：php bin/hyperf.php start，看到 Server started on https://www.php.cn/link/85237feeff817d9ae295ca736165879d 即可
- 浏览器打开 https://www.php.cn/link/85237feeff817d9ae295ca736165879d，出现 “Hyperf” 字样页面，说明通了
整个过程不依赖图形界面、不碰虚拟机设置、不改 BIOS，只要网络通畅，10 分钟内从裸 Ubuntu 到第一个接口响应，就是最贴近小白的“光速”。
