Composer安装Hyperf框架教程 高性能微服务搭建指南【实操】

Hyperf 需 php 8.0+、启用 swoole/openssl/json/mbstring/curl 扩展且无 disable_functions 限制；创建项目应指定稳定版本并配置 .env 与 dev.php 启用调试，启动前务必验证基础响应。

Hyperf 不是靠 composer create-project 一键生成就能跑起来的“开箱即用”框架——它依赖 PHP 8.0+、Swoole 扩展、以及明确的扩展启用状态，缺一不可。直接运行安装命令却启动失败，90% 是卡在环境校验或扩展加载上。

检查 PHP 版本和必需扩展是否就位

Hyperf 3.x 要求 PHP ≥ 8.0，且必须启用 swoole、openssl、json、mbstring、curl。仅装了 Swoole 扩展但没启用（比如被 disable_functions 拦截），也会导致 php bin/hyperf.php start 报 class 'SwoolehttpServer' not found。

• 运行 php -v 确认版本 ≥ 8.0
• 运行 php -m | grep swoole 看是否列出；若无，需编译安装或通过 pecl install swoole（注意匹配 PHP 版本）
• 运行 php --ri swoole 查看输出中 support async_redis => enabled 等关键项是否为 enabled，不是则需检查 php.ini 中是否漏加 extension=swoole.so
• disable_functions 若包含 pcntl_fork、exec 等，会阻止 Hyperf 启动时的进程管理，务必移除

用 composer create-project 创建项目时的关键参数

官方推荐命令是 composer create-project hyperf/hyperf-skeleton，但它默认拉取最新稳定版（可能含 breaking change）。生产环境建议锁死版本，避免因 minor 升级引发协程上下文或注解解析异常。

• 指定版本：如 composer create-project hyperf/hyperf-skeleton:3.1.25（查最新 patch 版见 GitHub Releases）
• 跳过脚本执行（防权限/路径问题）：--no-scripts，后续手动运行 php bin/hyperf.php start 更可控
• 若 Composer 镜像慢或报 file could not be downloaded，先执行 composer config -g repo.packagist composer https://packagist.phpcomposer.com 切换国内镜像（注意：PHP Composer 官方镜像已停用，推荐阿里云或腾讯云镜像）

启动前必须改的两个配置文件

新项目默认监听 0.0.0.0:9501，但开发机若开了防火墙或 docker 网络隔离，会连不上；同时 app_ENV=dev 下未开启调试模式，报错不显示堆栈。

• 修改 .env：确保 APP_ENV=dev 且 SWOOLE_HTTP_HOST=0.0.0.0、SWOOLE_HTTP_PORT=9501（非 127.0.0.1，否则容器外无法访问）
• 修改 config/autoload/dev.php：把 'debug' => false 改成 true，否则 500 错误只返回空白页
• 若用 Docker，还需确认 docker run -p 9501:9501 映射正确，且容器内 php 进程能读取 /proc/sys/net/core/somaxconn（Swoole 启动需该值 ≥ 511）

Hyperf 的“高性能”建立在 Swoole 协程 + 自动依赖注入 + 注解扫描之上，但这也意味着：任何阻塞操作（如未用 Co::sleep() 替代 sleep()）、或注解写错位置（比如 @Controller 加在普通类而非 AppController 下），都会让服务静默失败——这类问题不会报错，只会让接口无响应。动手前先跑通 curl http://127.0.0.1:9501 返回 “Hello Hyperf” 再加业务逻辑，比急着写微服务更省时间。