单台云服务器从零搭建Hyperf项目完整流程

游戏科技网2026年09月15日 01:10云服务器10

描述：必须安装 hyperf/http-server 才能启动 HTTP 服务，否则 php bin/hyperf.php start 后无端口监听、curl 超时；安装后默认监听 0.0.0.0:9501，无需额外配置。直接上手，不绕弯子。单台云服务器跑 Hyerf 项目，核心就四件事：连得上、装得对、…

必须安装 hyperf/http-server 才能启动 HTTP 服务，否则 php bin/hyperf.php start 后无端口监听、curl 超时；安装后默认监听 0.0.0.0:9501，无需额外配置。

直接上手，不绕弯子。单台云服务器跑 Hyerf 项目，核心就四件事：连得上、装得对、跑得稳、访得着。中间没玄学，但有几个关键点容易卡住——比如没装 hyperf/http-server 就启动，看着进程在跑，其实根本没监听端口；又比如路由写了 /api/ 结尾斜杠，结果全 404。下面按真实操作顺序拆解。

连上服务器并初始化环境

买完服务器后，你会拿到公网 IP、用户名（一般是 root）、密码和 SSH 端口（默认 22）。

Windows 用户用 Xshell 或 FinalShell，填 IP、端口、用户名、密码，点连接就行
Mac / Linux 用户直接终端执行：ssh root@你的公网IP，输密码（输的时候不显示，正常）

首次登录后，先做三件事：

更新系统：apt update && apt upgrade -y（Ubuntu）或 yum update -y（CentOS）
装基础工具：apt install -y git curl wget unzip vim
创建普通用户（安全起见）：adduser deploy && usermod -aG sudo deploy，之后建议改用这个用户操作

装 PHP 环境和 Hyperf 骨架

Hyperf 要求 PHP ≥ 7.4（推荐 8.1+），且必须启用 sockets、pcntl、openssl、json 等扩展。别跳过验证：

先装 PHP：apt install -y php8.1-cli php8.1-mbstring php8.1-xml php8.1-curl php8.1-sqlite3 php8.1-zip
确认扩展已加载：php -m | grep -E "sockets|pcntl|openssl"，缺哪个补哪个
装 Composer：curl -sS https://getcomposer.org/installer | php && mv composer.phar /usr/local/bin/composer
创建项目：composer create-project hyperf/hyperf-skeleton myapp

注意：骨架默认不含 HTTP 服务组件，必须手动装——否则 php bin/hyperf.php start 启动后 curl http://127.0.0.1:9501 会超时。

Hyperf 3.2.4

Hyperf 3.2.4 官方源码下载，适合 PHP 协程框架、微服务组件和高并发应用升级，覆盖 3.2 分支新增函数与稳定性优化。

下载

进项目目录：cd myapp
执行：composer require hyperf/http-server

配置与启动服务

Hyperf 默认监听 0.0.0.0:9501，但要让外网访问，还得打开防火墙端口，并确认服务真正跑起来了。

开放端口（Ubuntu）：ufw allow 9501；（CentOS）：firewall-cmd --permanent --add-port=9501/tcp && firewall-cmd --reload
启动服务：php bin/hyperf.php start（别 background 运行，先看日志是否报错）
验证是否监听：netstat -tuln | grep :9501 或 ss -tuln | grep :9501
本地测试：curl http://127.0.0.1:9501 应返回欢迎页或你写的响应

如果启动卡住或无响应，优先检查：

端口是否被占：lsof -i :9501（Linux/macOS）或 netstat -ano | findstr :9501（Windows WSL）
路由是否注册成功：php bin/hyperf.php route:list，确保你的控制器路径出现在列表里
AutoController 的 prefix 别加结尾斜杠，#[AutoController(prefix: /api)] 正确，/api/ 错误

让域名或 IP 直接访问

现在服务只在 9501 端口运行，浏览器输 http://你的IP:9501 才能访问。想用 http://你的IP 或域名直接打开，有两个轻量方案：

Nginx 反向代理（推荐）：装 Nginx，配一个 conf 指向本地 9501：
location / { proxy_pass http://127.0.0.1:9501; proxy_set_header Host $host; }
然后开放 80 端口，重启 Nginx 即可
改 Hyperf 监听端口（简单）：编辑 config/autoload/server.php，把 port => 9501 改成 80，再启动（需 root 权限）

若要用域名，记得提前在 DNS 后台添加 A 记录指向服务器公网 IP，等解析生效（通常几分钟到几小时）。