Composer 无法安装 Swoole 扩展本身，仅引入空包；Swoole 是需通过 pecl 或源码编译安装的 C 扩展，并在 php.ini 中启用，否则 php -m 查不到、php --ri 报错、composer 因 ext-swoole 依赖失败。
Composer 不能直接安装 Swoole 框架，它只能装 PHP 扩展的“伪包”或封装层；真正起作用的是已编译并启用的 swoole 扩展本身。
为什么 composer require swoole/swoole 不等于装好了 Swoole？
这个命令只是把一个空的 Composer 包拉进 vendor/，它不编译、不加载、不检查 PHP 环境。Swoole 是 PHP 的 C 扩展，必须通过 pecl install swoole 或源码 ./configure && make && make install 安装，并在 php.ini 中显式启用 extension=swoole.so（Linux/macOS）或 extension=php_swoole.dll（Windows）。否则：
• php -m | grep swoole 无输出
• php --ri swoole 报错 Extension 'swoole' not found
• composer install 遇到 "ext-swoole": "*" 依赖时直接失败
pecl install swoole 和源码编译，选哪个？
多数情况推荐 pecl install swoole：自动匹配当前 php-config 路径，省去手动指定参数的麻烦。但要注意：
• 必须先确认 php-config 指向你实际用的 PHP 版本（多版本共存时极易填错）
• PECL 默认不开启协程 Hook，而 Laravel Octane、Hyperf 等强依赖 --enable-coroutine
• 若需 --enable-http（HTTP Server）、--enable-mysqlnd（协程 MySQL），PECL 安装后无法补加，只能重装或改用源码编译
• 源码编译更可控，推荐命令：cd swoole-src && ./configure --enable-coroutine --enable-http --enable-mysqlnd --with-php-config=/usr/bin/php-config
装完扩展后，composer install 还失败？检查这三处
常见卡点不是 Composer 本身，而是环境没对齐：
• php -i | grep "Loaded Configuration File" 输出的 php.ini 路径，是否真被你修改了？CLI 和 FPM 的配置文件常不同
• extension=swoole.so 是否写在该 php.ini 文件末尾？有没有拼错成 swoole（少 .so）或路径错误？
• 修改后是否重启了对应进程？php-fpm 需 systemctl restart php-fpm，CLI 不用重启，但 Apache 要 systemctl restart apache2
Laravel + Swoole 启动报错，最常漏掉的配置项
用 swooletw/laravel-swoole 时，光装好扩展远远不够：
• APP_URL 必须是 http://127.0.0.1:1215 或真实域名，不能是 http://localhost（中间件生成 URL 会出错）
• SWOOLE_HTTP_HOST 和 SWOOLE_HTTP_PORT 必须在 .env 中显式定义，否则默认值可能被防火墙拦截
• config/swoole_http.php 中的 server → mode 建议设为 SWOOLE_PROCESS，SWOOLE_BASE 模式下协程调度易干扰 Laravel 生命周期
• Session 默认失效——关掉 config/swoole_http.php 的 session 配置，改用 SESSION_DRIVER=redis，且 redis 的 scheme 必须是 tcp，不能是 unixsocket
真正难的从来不是敲哪条命令，而是搞清「PHP CLI 加载哪个 php.ini」「Swoole 扩展到底由谁提供」「框架启动时用的是哪个 PHP SAPI」——这三个问题没理清，所有 composer require 都只是往坑里多扔一包水泥。
