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 进程根本没加载新扩展。
