swoole 是 php 扩展而非 composer 包，需通过 pecl 安装并配置 php.ini 启用；项目中仅需在 dev 依赖中添加 swoole/ide-helper 提供类型提示，不可 require swoole/swoole 或 ext-swoole。
composer install 时提示 swoole 扩展未启用
这不是 Composer 的问题，而是 PHP 运行时缺少 swoole 扩展。Composer 只负责下载代码、执行脚本，它不会、也不能自动帮你装 PHP 扩展。
常见错误现象：Class 'Swoole\Http\Server' not found 或 Extension 'swoole' not loaded，哪怕 composer require swoole/ide-helper 成功了也照样报错。
- 先确认 PHP CLI 是否加载了
swoole：运行php -m | grep swoole；没输出就说明没装好 -
composer require swoole/swoole是无效的——官方没有发布这个包，别信网上过时教程 - 真正要装的是 PECL 扩展：
pecl install swoole（需先配好phpize和编译环境） - 装完后检查
php.ini是否有extension=swoole.so（Linux/macOS）或extension=php_swoole.dll（Windows）
项目里该 require 哪个 swoole 包？
绝大多数情况，你不需要在 composer.json 中 require 任何 swoole 相关包——因为 swoole 是 PHP 扩展，不是纯 PHP 库。
唯一需要 Composer 管理的，是 IDE 支持或类型提示辅助：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 开发时加
"swoole/ide-helper": "^4.12"（对应 Swoole 4.x）或"swoole/ide-helper": "^5.0"（Swoole 5.x），仅用于 PhpStorm/VS Code 补全 - 不要加
"ext-swoole": "*"到require，这只会让composer install检查扩展是否存在，不解决实际依赖 - 生产环境部署时，
composer install --no-dev会跳过ide-helper，不影响运行
为什么 composer update 后 Swoole 服务起不来了？
大概率是 Swoole 主版本升级（比如从 4.x 升到 5.x），API 有破坏性变更，而你的代码没适配。
Swoole 5.x 移除了 Swoole\Http\Request::$rawContent，改用 $request->getContent()；onReceive 回调参数签名也变了。
- 检查
composer.lock里swoole/ide-helper的版本是否和实际php --ri swoole输出的 Swoole 版本一致 - 升级前务必看官方 版本更新日志，重点关注
Breaking Changes部分 - CI 中建议固定扩展版本：Dockerfile 里用
pecl install swoole-4.11.4，而不是pecl install swoole
本地开发用 Docker，怎么让 composer install 和 Swoole 同时生效？
Docker 容器里 PHP 镜像默认不含 swoole，光跑 composer install 没用，得先编译扩展再装依赖。
典型错误：Dockerfile 先 RUN composer install，再 RUN pecl install swoole——这时 PHP 还没加载扩展，后续 php artisan serve 或自定义启动脚本仍会失败。
- 顺序必须是：安装构建依赖 → 编译安装
swoole→ 启用扩展 → 再运行composer install - 推荐基础镜像用
php:8.2-cli而非php:8.2-apache，后者默认禁用pcntl，影响 Swoole 进程管理 - 在
docker-compose.yml的command或启动脚本里，加一句php -m | grep swoole || exit 1，早发现扩展没加载
php.ini 配置不一致，导致本地能跑线上报错。
