Hyperf 依赖管理需严格遵循协程安全原则：必须用 create-project 创建骨架，禁用 --no-dev/--no-scripts，使用协程组件（如 hyperf/http-client），并正确配置 autoload；否则将导致类未加载、协程阻塞或进程崩溃。

Hyperf 是基于 Swoole 的协程 PHP 框架，composer 在其中的用法和传统 Laravel 或普通 PHP 项目基本一致，但有几处关键差异必须注意：Hyperf 对 PHP 版本、扩展依赖更严格，且部分组件（如数据库驱动、Redis 客户端）需选用协程兼容版本。

安装 Hyperf 项目时必须用 composer create-project

不能直接 composer require hyperf/hyperf 到已有项目——Hyperf 不是“可插拔”的包，而是一套完整骨架，依赖目录结构、配置加载顺序和启动生命周期。

正确做法：

composer create-project hyperf/hyperf-skeleton my-app
cd my-app
php bin/hyperf.php start

该命令会自动拉取 hyperf/hyperf-skeleton 并执行 composer install，同时确保 vendor/hyperf/* 下所有组件版本对齐。手动 require 单个 hyperf/xxx 包极易引发版本冲突或类未加载问题。

composer require 添加协程安全的第三方包

Hyperf 运行在协程环境，所有 I/O 操作（HTTP 请求、Redis、MySQL、文件读写）必须使用协程友好的客户端。直接 require guzzlehttp/guzzle 或 predis/predis 会导致协程阻塞、性能归零甚至进程崩溃。

应优先选用 Hyperf 官方维护或社区验证的协程适配包：

• hyperf/http-client 替代 Guzzle（已内置，无需额外 require）
• hyperf/redis 替代 Predis（自动使用 swoole_redis 协程客户端）
• hyperf/database + hyperf/db-connection 替代原生 PDO（支持协程 MySQL 连接池）
• 若需 HTTP 调用外部服务，直接用 Hyperf\HttpClient\HttpClientFactory，不要 new GuzzleClient

错误示例（导致协程阻塞）：

composer require guzzlehttp/guzzle
// 然后在代码里：
$client = new \GuzzleHttp\Client(); // ❌ 阻塞式，破坏协程

正确方式（使用 Hyperf 自带协程 HTTP 客户端）：

$client = $this->container->get(\Hyperf\HttpClient\HttpClientFactory::class)->create(); // ✅

更新依赖时禁用 --no-dev 和跳过脚本

Hyperf 启动前会执行 Hyperf\Devtool\Composer\ScriptHandler::build 脚本，用于生成代理类、扫描注解、构建容器等。若运行 composer update --no-dev 或加 --no-scripts，会导致 runtime/container 目录缺失、注解失效、DI 容器无法解析依赖。

日常开发中应始终保留 dev 依赖并允许执行脚本：

• 运行 composer update 时，不加任何跳过参数
• 生产部署若需精简，应使用 composer install --no-dev --optimize-autoloader，而非 update
• 确认 composer.json 中 "scripts" 区块存在 "post-autoload-dump" 和 "post-update-cmd" 调用 Hyperf\Devtool\Composer\ScriptHandler

常见报错现象：Class xxx does not exist 或 Call to undefined method Hyperf\Contract\ContainerInterface::get()，大概率是脚本未执行导致代理类或容器配置未生成。

自定义组件或私有包需注意 autoload 配置

Hyperf 使用 PSR-4 自动加载，但要求命名空间与目录结构严格匹配，且必须显式声明在 composer.json 的 "autoload" 中。仅把类文件扔进 app/ 下不会被自动识别。

例如，添加一个 App\Service\Payment\AlipayService，需确保：

• 类文件路径为 app/Service/Payment/AlipayService.php

• composer.json 中包含：

  "autoload": {
      "psr-4": {
          "App\\": "app/"
      }
  }

• 执行 composer dump-autoload（Hyperf 启动时也会触发，但手动执行可快速验证）

漏掉 dump-autoload 或命名空间写错（如写成 App\Service\Pay\AlipayService 但目录是 Payment），都会导致 Class not found。

Hyperf 的依赖管理本身不特殊，特殊的是它对协程安全性和启动脚本的强依赖。最常出问题的地方不是 composer 命令本身，而是绕过骨架约定、混用非协程组件、或跳过 post-install 脚本——这些操作在传统框架里可能只是“慢一点”，在 Hyperf 里直接表现为功能失效或进程挂死。

# mysql  # php  # laravel  # redis  # js  # json  # composer  # app  # ai  # swoole  # 命名空间  # require  # pdo  # class  # undefined  # database  # 数据库  # http  # 客户端  # 跳过  # 加载  # 的是  # 若需  # 也会  # 已有  # 自动识别  # 自定义  # 自带