Composer 无法安装 Swoole 运行时扩展，swoole/swoole 包仅为 IDE 补全用的空壳；必须通过 pecl 或源码编译安装 swoole.so，并确认 PHP 版本 ≥8.0、禁用函数未屏蔽关键系统调用、框架配置与扩展能力对齐。
Composer 不能直接安装 Swoole 运行时扩展，只能装它的 PHP 封装库（如 swoole/swoole），但该库不提供实际功能——它只是个空壳，无法替代 pecl install swoole 或源码编译安装的原生扩展。
为什么 composer require swoole/swoole 没用？
这个包是 Swoole 官方发布的“伪包”，仅含少量 stub 和 autoload 配置，不包含任何 C 扩展代码。PHP 运行时仍需真实加载 swoole.so，否则调用 Swoole\Http\Server 会直接报错：Class 'Swoole\Http\Server' not found。
- 它对 IDE 补全、静态分析有微弱帮助，但对运行毫无作用
- Hyperf、Laravel-Swoole 等框架依赖的是 PHP 扩展本身，不是这个 Composer 包
- 某些旧教程误传“装了就能跑”，结果卡在启动阶段，浪费大量排查时间
真正要做的三件事（缺一不可）
环境就绪才有后续可言。别跳步，尤其别信“一键安装”。
- 确认 PHP 版本：
php -v必须 ≥ 8.0（Swoole 5.x 要求；4.x 最低支持 7.4，但已停止维护） - 安装并启用扩展：
pecl install swoole（推荐），或从github.com/swoole/swoole-src源码编译，完成后检查php --ri swoole输出中support async_redis => enabled等关键项为enabled - 检查禁用函数：
disable_functions里不能有pcntl_fork,exec,shell_exec等，否则 Hyperf/LaravelS 启动即失败
不同框架对 Swoole 的配置差异点
装好扩展只是起点。各主流框架对端口、host、session、Redis 连接方式等有硬性要求，填错一个就启动失败或路由失效。
- Laravel +
swooletw/laravel-swoole：APP_URL必须设为http://127.0.0.1:1215（不能是localhost），config/swoole_http.php中server → mode建议设为SWOOLE_PROCESS - Hyperf：
.env中必须显式设SWOOLE_HTTP_HOST=0.0.0.0（非127.0.0.1），否则 Docker 外无法访问；config/autoload/dev.php中'debug' => true否则 500 错误不报堆栈 - LaravelS（
hhxsv5/laravel-s）：默认监听5200端口，Nginx 反向代理必须配upstream laravels { server 127.0.0.1:5200; }，且proxy_set_header不能漏掉X-Forwarded-For和Host
启动失败最常卡在哪几个地方？
90% 的启动问题集中在端口、协程兼容、自动加载三类，日志比猜更有用。
-
Address already in use：查netstat -tuln | grep :1215，杀残留进程或改SWOOLE_HTTP_PORT=1216 - 空白页 / 500 且
storage/logs/swoole_http.log提示Class not found：执行rm bootstrap/cache/*.php && composer dump-autoload - Session 不生效：关掉
config/swoole_http.php里的 session 配置，改用 Redis 驱动，并确保SESSION_DRIVER=redis和redis配置中scheme是tcp（不是unixsocket）
真正麻烦的从来不是装，而是装完之后那一堆隐式依赖和配置耦合——比如 Laravel 的 URL 生成机制、Hyperf 的协程上下文、Nginx 的 header 透传规则。这些地方没对齐，服务就起不来，或者起得来但行为诡异。多看日志，少凭感觉改。
