Linux下安装PHP Hyperf并运行Hello World应用

花开有时

发布时间：2026-09-20 | 3人浏览过

原创

在 Linux 上运行 Hyperf，核心步骤并不复杂：先准备符合要求的 PHP CLI 环境和 Swoole 网络引擎，再使用 Composer 创建 Hyperf 项目，添加一个 Hello World 路由和控制器，最后启动 Hyperf HTTP Server 并通过浏览器或 curl 验证结果。

本文以直接安装到 Linux 主机的方式演示，不依赖 Docker。命令示例主要按照 Debian、Ubuntu 一类系统编写；如果使用 Rocky Linux、AlmaLinux 等发行版，PHP、编译工具等系统软件包需要改用对应的 dnf 或 yum 安装，进入 Composer 和 Hyperf 阶段后的操作基本一致。

一、安装 Hyperf 前需要准备什么

Hyperf 与传统通过 PHP-FPM 执行一次请求、结束一次进程上下文的 PHP 应用有所不同。它会启动一个长期运行的 Server，因此除了 PHP 本身，还需要 Swoole 或 Swow 这样的网络引擎。

按照当前 Hyperf 官方 Skeleton 的环境要求，PHP 至少需要 8.2，网络引擎可以选择 Swoole 5.0 及以上或 Swow 1.3 及以上。本文选择资料更多、使用较普遍的 Swoole 路线。

组件	本文要求	作用
Linux	常见服务器发行版即可	运行 PHP、Swoole 和 Hyperf
PHP	PHP 8.2 或更高版本	执行 Hyperf PHP 代码
Swoole	5.0 或更高版本	提供 HTTP Server、协程和网络能力
Composer	Composer 2.x	安装 Hyperf 及其 PHP 依赖

SVG 配图 1 — 图 1：Hyperf 原生运行环境由 Linux、PHP、网络引擎和 Composer 共同组成。

二、检查 Linux 上现有的 PHP 环境

不要急着运行 Composer。先检查服务器是否已经安装 PHP，以及当前命令行实际使用的是哪个版本：

php -v
which php
php --ini

如果已经是 PHP 8.2 或更高版本，可以继续检查扩展。如果版本低于 8.2，应先通过当前 Linux 发行版的软件源或 PHP 软件仓库升级 PHP。

在 Debian、Ubuntu 一类系统上，如果系统的软件源已经提供 PHP 8.2 或以上版本，可以先安装命令行环境和后续编译 Swoole 常用的工具：

sudo apt update

sudo apt install -y \
    php-cli \
    php-dev \
    php-pear \
    php-mbstring \
    php-bcmath \
    php-curl \
    php-xml \
    php-zip \
    build-essential \
    autoconf \
    pkg-config \
    unzip \
    git \
    curl

安装后再次执行：

php -v

示例输出：

PHP 8.x.x (cli) (built: ...)
Copyright (c) The PHP Group

注意：这里的 8.x.x 只是示例。真正需要判断的是版本是否满足 PHP 8.2 或更高，不必追求和示例完全相同。

检查 Hyperf 需要的基础扩展

可以先查看当前 CLI PHP 已经加载了哪些模块：

php -m

对于最基础的 HTTP Hello World 应用，至少应重点确认 JSON、PCNTL 等基础能力可用：

php -m | grep -Ei 'json|pcntl|bcmath'

如果以后要连接 MySQL、Redis 或使用 HTTPS，还应根据实际功能准备 PDO、Redis、OpenSSL 等扩展。不要因为项目以后可能使用某个组件，就在 Hello World 阶段一次安装所有扩展。

三、安装并启用 Swoole

本文使用 PECL 安装 Swoole。由于前面已经安装了 php-dev、php-pear 和编译工具，可以直接执行：

sudo pecl install swoole

编译过程中可能根据 Swoole 版本询问是否启用某些可选功能。如果当前目标只是启动普通 Hyperf HTTP 服务，可以按照默认配置完成安装；MySQL Native Driver、Socket、cURL Hook 等可选功能是否开启，应根据后续项目需求决定。

PECL 编译结束后，如果终端提示已经成功安装 swoole.so，下一步是让 PHP CLI 加载这个扩展。

Debian、Ubuntu 软件包形式的 PHP 可以先取得当前 PHP 主次版本：

PHP_MM="$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')"
echo "$PHP_MM"

然后建立 Swoole 配置：

printf "extension=swoole.so\nswoole.use_shortname=Off\n" \
| sudo tee "/etc/php/${PHP_MM}/mods-available/swoole.ini"

sudo phpenmod swoole

重新打开终端不是必须的，因为 PHP CLI 每次执行都会重新读取配置。直接检查即可：

php --ri swoole

也可以只看版本：

php -r 'echo swoole_version(), PHP_EOL;'

如果能够输出 Swoole 版本号，说明 PHP 已经成功加载扩展。

Hyperf 官方 Skeleton 对 Swoole 的要求中特别注明 swoole.use_shortname 应设为 Off。

如果你的发行版不是 Debian 或 Ubuntu，不要照搬 /etc/php/.../mods-available/ 路径。执行下面的命令：

php --ini

找到 Scan for additional .ini files in 对应的目录，在该目录创建一个例如 99-swoole.ini 的文件：

extension=swoole.so
swoole.use_shortname=Off

SVG 配图 2 — 图 2：Linux 原生安装 Hyperf 的实际操作顺序。

四、安装 Composer

如果服务器已经安装 Composer，可以直接检查版本：

composer --version

只要能够正常输出 Composer 版本，就可以继续。如果当前系统软件源提供 Composer 2.x，也可以直接通过包管理器安装，例如 Debian、Ubuntu：

sudo apt install -y composer

然后再次确认：

composer --version

Hyperf 官方推荐通过 Composer 的 create-project 创建 Skeleton 项目，而 Composer 的 create-project 本身就是用于从现有项目包初始化新项目。

五、使用 Composer 创建 Hyperf 项目

选择准备保存项目的目录。下面以 /var/www 为例：

cd /var/www

composer create-project hyperf/hyperf-skeleton hyperf-hello

这里的 hyperf-hello 是我们自己指定的项目目录名。执行完成后，Composer 会把 Hyperf Skeleton 和所需组件安装到：

/var/www/hyperf-hello

官方 Skeleton 当前给出的标准创建命令也是：

composer create-project hyperf/hyperf-skeleton path/to/install

也就是说，我们只是把官方示例中的 path/to/install 换成了实际项目目录。

进入项目：

cd /var/www/hyperf-hello

可以先检查 Composer 所需的 PHP 环境是否全部满足：

composer check-platform-reqs

如果检查结果没有报告缺失的关键扩展，再继续下面的步骤。此时项目目录大致会包含：

app/
bin/
config/
runtime/
vendor/
composer.json
.env
...

其中本文最需要关注三个位置：

app/Controller/：放置 HTTP 控制器。
config/routes.php：配置请求 URL 与控制器之间的对应关系。
bin/hyperf.php：Hyperf 命令入口，启动服务时会用到。

六、创建 Hello World 控制器

为了让示例结构更接近实际项目，我们不把所有逻辑直接写在路由闭包里，而是单独创建控制器。

新建文件：

app/Controller/HelloController.php

写入下面的完整代码：

<?php

declare(strict_types=1);

namespace App\Controller;

class HelloController
{
    public function index(): string
    {
        return 'Hello World';
    }
}

这个控制器只有一个 index() 方法。收到请求后，它直接返回字符串 Hello World，没有数据库、模板或其他依赖，适合用来判断 Hyperf 的最基础 HTTP 链路是否已经工作。

七、添加 /hello 路由

打开：

config/routes.php

项目本身可能已经存在默认路由，不需要删除。确认文件已经引入 Router 后，增加一条：

Router::get('/hello', 'App\Controller\HelloController@index');

例如，一个最小化的 config/routes.php 可以写成：

<?php

declare(strict_types=1);

use Hyperf\HttpServer\Router\Router;

Router::get('/hello', 'App\Controller\HelloController@index');

这条配置表达的关系非常直接：

浏览器发起 GET /hello 请求；
Hyperf Router 找到 HelloController；
调用其中的 index() 方法；
把 Hello World 返回给客户端。

SVG 配图 3 — 图 3：访问 /hello 时，请求从 9501 端口进入 Hyperf，再由路由找到控制器并返回结果。

八、启动 Hyperf HTTP Server

确认当前终端位于项目根目录：

cd /var/www/hyperf-hello

执行 Hyperf 官方 Skeleton 提供的启动方式：

php bin/hyperf.php start

官方 Skeleton 默认 HTTP Server 监听 0.0.0.0:9501，当前配置中默认端口也为 9501。

正常情况下，终端会出现 Server 和 Worker 已经启动的相关日志。下面仅表示输出形式，属于示例输出：

[INFO] Worker#0 started.
[INFO] HTTP Server listening at 0.0.0.0:9501

启动命令会一直占用当前终端，这是正常现象，因为 Hyperf Server 正在持续运行，不要把它误认为程序卡住。

九、访问 Hello World

保持 Hyperf Server 运行，再打开另一个 SSH 终端，在服务器本机执行：

curl http://127.0.0.1:9501/hello

预期结果：

Hello World

看到这个结果，就说明下面整条链路已经正常：

Linux
  ↓
PHP CLI
  ↓
Swoole
  ↓
Hyperf HTTP Server
  ↓
Router
  ↓
HelloController@index
  ↓
Hello World

如果服务器有公网 IP，并且确实希望直接从自己的电脑访问，还可以使用：

http://服务器IP:9501/hello

但这要求云服务器安全组和 Linux 防火墙允许 TCP 9501 端口。

开发环境可以临时开放 9501 进行验证，但生产环境通常不建议直接把 Hyperf 的服务端口暴露给公网。更常见的做法是在前面部署 Nginx，由 Nginx 监听 80/443，再反向代理到本机 Hyperf 端口。

十、修改代码后为什么没有立即生效

这是初次从 PHP-FPM 转到 Hyperf 时很容易遇到的问题。

传统 PHP-FPM 应用通常在每次请求时重新加载脚本，而 Hyperf 是常驻内存服务。你修改了控制器或配置文件以后，已经运行的 Worker 不一定会自动重新加载新代码。

在当前最基础的学习阶段，最简单的办法是停止 Server：

Ctrl + C

然后重新执行：

php bin/hyperf.php start

因此，如果已经把：

return 'Hello World';

修改为：

return 'Hello Hyperf';

却仍然看到旧内容，先重启 Hyperf 服务再判断是不是代码本身的问题。

十一、常见问题怎么排查

1. Composer 提示缺少 ext-swoole

典型原因不是没有执行过 PECL，而是当前运行 Composer 的 PHP CLI 没有加载 Swoole。

先执行：

php --ri swoole

如果提示扩展不存在，再检查：

php --ini

确认刚才添加的 Swoole INI 文件是否位于 CLI PHP 实际扫描的目录。

还要注意服务器中可能同时安装了多个 PHP，例如 PHP 8.1、8.2、8.3 共存。这时 pecl 编译扩展时使用的 PHP，可能和 php 命令实际指向的版本并不一致。

可以同时检查：

which php
php -v
which phpize
phpize --version
which php-config
php-config --version

2. Swoole 已安装，但 Hyperf 仍提示环境不符合要求

检查实际 Swoole 版本：

php -r 'echo swoole_version(), PHP_EOL;'

如果版本低于当前 Hyperf Skeleton 要求的 5.0，需要升级 Swoole，而不是继续修改 Hyperf 项目代码。

3. 启动后访问 9501 显示 Connection refused

先在运行 Hyperf 的服务器本机检查：

curl http://127.0.0.1:9501/hello

如果本机也拒绝连接，说明问题通常发生在 Hyperf 启动阶段。检查运行 php bin/hyperf.php start 的终端是否已经报错退出。

如果本机访问正常，而外部电脑无法访问，再检查监听端口：

ss -lntp | grep 9501

然后检查云服务器安全组和 Linux 防火墙。这时就不要继续修改 PHP 控制器，因为 HTTP 应用本身已经可以在本机正常响应。

4. curl 返回 404 Not Found

服务器能连接但返回 404，说明网络和 Hyperf Server 基本已经正常，问题更可能在路由层。

重点检查：

config/routes.php

是否真的包含：

Router::get('/hello', 'App\Controller\HelloController@index');

同时确认控制器文件路径：

app/Controller/HelloController.php

类的命名空间应为：

namespace App\Controller;

修改之后记得重新启动 Hyperf Server。

5. 9501 端口已经被其他程序使用

执行：

ss -lntp | grep 9501

如果已经有其他服务占用该端口，可以停止冲突服务，也可以修改 Hyperf 的 Server 配置。默认配置文件位于：

config/autoload/server.php

其中 HTTP Server 的核心配置类似：

'host' => '0.0.0.0',
'port' => 9501,

例如把端口改成 9502 后，重新启动 Hyperf，并改为访问：

curl http://127.0.0.1:9502/hello

十二、最终检查：怎样算安装成功

判断 Hyperf 是否真正安装完成，不应该只看 Composer 有没有下载完文件。下面几项全部通过，才说明从 PHP 环境到 HTTP 请求的基本链路已经建立。

SVG 配图 4 — 图 4：从 PHP 环境到 HTTP 响应的最终验证清单。

最终可以依次执行这组命令进行快速确认：

php -v

php --ri swoole

composer --version

cd /var/www/hyperf-hello

composer check-platform-reqs

php bin/hyperf.php start

然后在另一个终端执行：

curl http://127.0.0.1:9501/hello

能够得到：

Hello World

结语

Linux 下安装 Hyperf 的关键并不只是执行一条 Composer 命令，而是把运行链路逐层确认清楚：PHP CLI 版本要满足要求，Swoole 必须由同一个 PHP CLI 正确加载，Composer 再负责创建 Hyperf Skeleton，最后由 php bin/hyperf.php start 启动常驻的 HTTP Server。

当 /hello 能稳定返回 Hello World 后，就已经完成了一个最小但完整的 Hyperf 应用。后续无论增加数据库、Redis、依赖注入、中间件还是业务控制器，本质上都是在这套已经跑通的项目结构上继续扩展。

环境要求、Composer 创建方式、默认启动命令与 9501 端口根据 Hyperf 官方 Skeleton 当前说明核对。