composer怎么安装hyperf框架_通过composer部署微服务环境【实操】-composer-PHP中文网

直接使用 composer create-project hyperf/hyperf 会安装 dev-master 分支而非最新稳定版，应指定版本如 "3.2.*" 并确认 composer show 输出为 3.2.0；hyperf-skeleton 是预装模板，非增强版，需调整 minimum-stability 为 stable；php≥8.1、swoole≥5.0.3 为必需，docker 部署须用含 swoole 的镜像；consul 注册失败易静默，需检查 uri 和健康检查配置。

composer怎么安装hyperf框架_通过composer部署微服务环境【实操】

composer create-project 装出来的不是 Hyperf 最新稳定版

直接 composer create-project hyperf/hyperf 默认会拉取 dev-master 分支，也就是开发中的不稳定快照，不是 v3.1 或 v3.2 这类 tagged 版本。线上部署必须锁定稳定 tag，否则某天 composer update 可能突然 break。

装指定版本：用 composer create-project hyperf/hyperf project-name --prefer-dist -n 后立刻进目录执行 composer require hyperf/hyperf:v3.2.0
或者一步到位：composer create-project hyperf/hyperf project-name "3.2.*" --prefer-dist -n
检查是否生效：运行 composer show hyperf/hyperf，输出里 versions 行应显示 3.2.0（不是 dev-main 或带 dev- 前缀的）

hyperf-skeleton 与 hyperf/hyperf 的区别别搞混

官方有两个起手式：一个是 hyperf/hyperf（空骨架），一个是 hyperf/hyperf-skeleton（带常用组件预装）。新手常误以为后者是“增强版”，其实它只是个带 config/autoload 和 docker-compose.yml 的模板，核心框架包仍是 hyperf/hyperf。

Composer

Composer 是 PHP 生态常用依赖管理工具，用于安装框架、组件和项目依赖。

下载

微服务场景推荐从 hyperf/hyperf 开始，按需装组件，比如只加 hyperf/json-rpc 和 hyperf/consul，避免冗余依赖拖慢启动
如果用了 hyperf-skeleton，记得删掉不用的配置文件（如 autoload/cache.php），否则 Hyperf\Contract\ConfigInterface 可能因加载顺序异常报错
hyperf-skeleton 的 composer.json 里 "minimum-stability": "dev" 是隐患，必须改成 "stable" 并加 "prefer-stable": true

PHP 版本和 Swoole 扩展不匹配会导致 swoole_http_server 启动失败

Hyperf v3.x 要求 PHP ≥ 8.1、Swoole ≥ 5.0.3。但很多人用 apt install php-swoole 装的是系统源里的旧版（如 Ubuntu 22.04 自带 Swoole 4.8），结果 php bin/hyperf.php start 报 Class 'Swoole\Http\Server' not found 或直接 segfault。

确认 PHP 版本：php -v 输出至少是 8.1.0
确认 Swoole：php --ri swoole 查看 Version 行，低于 5.0.3 就得重装 —— 推荐用 pecl：pecl install swoole（自动适配当前 PHP）
Docker 部署时别用 php:8.1-cli 镜像，它不含 Swoole；改用 hyperf/hyperf:3.2-alpine 或自己写 Dockerfile 安装 swoole 扩展

微服务注册中心连不上时，consul 服务发现会静默失败

Hyperf 默认用 Consul 做服务注册，但 hyperf/consul 组件不会在启动时报错，而是等第一次调用 ConsulClient 时才抛异常，导致服务看似跑起来了，实际根本没注册成功。

检查 config/autoload/consul.php 中 'uri' 是否指向可访问的 Consul agent（如 'http://consul:8500'，不是 'localhost'）
加健康检查：在 config/autoload/services.php 里为每个 RPC 服务设 'check' => ['deregister_critical_service_after' => '90s']，避免节点宕机后服务仍挂在注册中心
本地调试时，Consul 必须运行且 curl http://127.0.0.1:8500/v1/status/leader 返回非空值，否则 Hyperf\Consul\Exception\ConsulException 会被吞掉

Hyperf 的微服务链路里，服务注册时机、配置加载顺序、Swoole 进程模型对协程上下文的影响，比 Laravel 之类更敏感。一个 config/autoload/dependencies.php 里漏写 Hyperf\Contract\ConfigInterface 的 alias，就能让整个服务发现失效，而且没明显报错。这种隐性依赖得多盯日志里 [DEBUG] Load config from 那几行。