在 ubuntu 服务器部署 hyperf 的关键是配齐 php 协程运行组件：php ≥8.1、swoole ≥5.0（禁用 shortname）、启用必需扩展、cli 下禁用 opcache，并补全 hyperf/http-server 组件；推荐 ubuntu 22.04 lts，避免 24.04 因 glibc 不兼容导致 swoole 加载失败。

在 Ubuntu 服务器上部署 Hyperf，核心不是装“某个发行版”，而是配齐 PHP 协程运行所需的底层组件。关键点很明确：PHP ≥ 8.1、Swoole ≥ 5.0（且禁用 shortname）、必需扩展启用、CLI 模式下禁用 opcache，再补全 http-server 组件——缺一不可，否则服务启动无声无息。

系统与 PHP 基础准备

推荐使用 Ubuntu 22.04 LTS（内核 ≥5.4，兼容 Swoole 协程调度），避免选用 24.04 ——其 glibc 2.39+ 与当前主流 Hyperf 镜像（如 hyperf/hyperf:8.1-alpine-v3.12-swoole）存在二进制不兼容，会导致 swoole 扩展加载失败或 SSL 符号未定义错误。

• 安装 PHP 8.3（或 8.1/8.2）：若用宝塔面板，直接勾选；若手动安装，需确保编译时启用 --enable-mbstring、--enable-pcntl、--enable-bcmath、--with-openssl、--with-pdo-mysql 等关键选项
• 验证 PHP 版本：php -v 输出应为 8.1+
• 检查基础扩展是否就位：php -m | grep -E 'json|mbstring|pcntl|openssl|pdo|redis' ——缺失项需单独安装（如 sudo apt install php-redis）

Swoole 扩展安装与校验

Swoole 是 Hyperf 的运行引擎，必须源码编译安装 v5.0+（Ubuntu 官方源的 php-swoole 包通常版本过低，不满足 Hyperf 3.1 要求）。

Hyperframes Animation

所有用于HyperFrames 的动画知识——原子运动规则、多阶段场景蓝图、场景过渡、更广泛的运动设计技术，以及...

下载

• 下载并解压 Swoole 5.1.3（或更高稳定版）：wget https://gitee.com/swoole/swoole-src/repository/archive/v5.1.3.tar.gz
• 进入解压目录，执行：/www/server/php/83/bin/phpize（路径按实际 PHP 安装位置调整）→ ./configure --with-php-config=/www/server/php/83/bin/php-config → make && sudo make install
• 编辑 php.ini，添加：extension=swoole，并确认关闭 shortname：swoole.use_shortname = Off
• 重启 PHP 或 Web 服务后验证：php --ri swoole 输出中必须含 coroutine => enabled 且 shortname => Off

创建项目并补全关键组件

官方骨架 hyperf/hyperf-skeleton 默认不含 HTTP 服务能力，跳过这步将导致 php bin/hyperf.php start 启动后无监听端口、curl 超时。

• 确保 Composer 已安装（建议 2.5+），并配置国内镜像加速：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer
• 创建项目：composer create-project hyperf/hyperf-skeleton myapp
• 进入项目目录，**立即执行**：composer require hyperf/http-server（注意：不是 composer install，后者只装 dev 依赖）
• 检查 composer.json 的 require 字段是否已包含 "hyperf/http-server": "^3.1"
• 禁用 CLI 模式 opcache：opcache.enable_cli = 0（在 php.ini 中设置，否则协程行为异常）

生产环境基础加固

上线前务必调整配置，避免前台运行中断、端口暴露、资源失控等问题。

• 关闭调试模式：APP_DEBUG=false（修改项目根目录 .env）
• 用 Supervisor 或 systemd 托管进程，例如 Supervisor 配置中指定 autostart=true、autorestart=true、user=www-data
• Nginx 反向代理示例（避免直接暴露 9501）：
  

  location / {<br>  proxy_pass http://127.0.0.1:9501;<br>  proxy_set_header Connection '';<br>  proxy_http_version 1.1;<br>}

• 根据服务器资源限制并发：在 .env 中设 SWOOLE_PROCESS_NUM=4、SWOOLE_MAX_COROUTINE=3000

整个过程不需要下载所谓“Hyperf Ubuntu 镜像”或定制 ISO，所有操作均基于标准 Ubuntu + 手动配置。只要版本对得上、shortname 关得掉、http-server 补得全、opcache 在 CLI 关得准，Hyperf 就能稳稳跑起来。