Swoole 是 PHP 的 C 扩展，须通过 pecl 或编译安装并启用 extension=swoole；composer require 安装的 swoole/swoole 等包仅为类型提示或 IDE 辅助，无法提供运行时协程能力。

直接装 swoole 扩展，不是装“Swoole 包”

很多人搜“composer 安装 swoole”，其实是混淆了概念：swoole 是 PHP 的 C 扩展，不是纯 PHP 的 Composer 包。你不能用 composer require swoole/swoole 装出一个能跑协程的 Swoole —— 那个包只是个空壳，仅用于类型提示或开发辅助。

真正起作用的是系统级的 swoole 扩展，必须通过 pecl 或编译安装，并确保 php.ini 中已启用 extension=swoole。

• 运行 php --ri swoole，有输出说明扩展已加载成功
• 若报错 Extension 'swoole' not found，Composer 再怎么 require 都没用
• composer require swoole/ide-helper 这类包只提供 IDE 补全，不提供运行时能力

composer require 能装哪些和 Swoole 相关的包？

真正适合 Composer 管理的，是基于 Swoole 构建的上层框架或工具库，比如：

• hyperf/hyperf：Swoole 生态最主流的协程框架，依赖 swoole 扩展
• swow/swow：另一个协程扩展（非 Swoole），但部分包会同时兼容两者
• topthink/think-swoole：ThinkPHP 的 Swoole 插件
• mix-php/mix：轻量级 Swoole 应用框架

这些包本身不包含 Swoole，它们在 composer.json 的 require 中声明 "ext-swoole": "^5.0"，Composer 会检查扩展是否存在及版本是否匹配。

立即学习“PHP免费学习笔记（深入）”；

执行 composer install 时若看到类似错误：

ext-swoole is missing from your system. Install or enable PHP's swoole extension.

说明不是包没装上，而是底层扩展根本没装好。

版本对不上？看清楚是扩展版本还是包版本

常见混乱点：Swoole 扩展版本（如 5.1.4） ≠ Hyperf 版本（如 v3.4.12） ≠ PHP 版本（如 8.2）。三者必须协同：

• Swoole v5.1+ 要求 PHP >=8.0；v4.8 是最后一个支持 PHP 7.4 的大版本
• Hyperf v3.x 要求 Swoole ^5.0；v2.6 只支持 Swoole ^4.6
• 运行 php -v 和 php --ri swoole | grep "Version" 确认实际环境
• 别光看 composer.json 里写的 "swoole/ide-helper": "^4.8"，那只是开发依赖，不影响运行

依赖检测失败时，先绕过再排查

开发阶段想快速验证逻辑，又暂时不想装 Swoole 扩展？可以临时跳过扩展检测：

• 加 --ignore-platform-req=ext-swoole：跳过 Swoole 扩展检查
• 加 --ignore-platform-reqs：跳过所有平台要求（含 PHP 版本、其他扩展）
• ⚠️ 但这只是“让 Composer 不报错”，不代表代码能跑 —— 启动 Hyperf 服务时仍会因缺扩展而崩溃
• 线上环境严禁使用 --ignore-platform-reqs，它掩盖的是真实兼容性风险

真要省事，推荐用官方 Docker 镜像，比如 hyperf/hyperf:8.2-alpine-v3.4，里面已预装对应版本的 PHP + Swoole + 扩展。

最常被忽略的一点：Swoole 扩展安装后，必须重启 PHP-FPM 或 Web 服务器，否则 phpinfo() 里看不到，php --ri swoole 也查不到 —— 不是 Composer 没装对，是 PHP 进程根本没加载新扩展。