swoole 的核心是 php 扩展而非 composer 包，必须通过 pecl install swoole 或源码编译安装并配置 php.ini，否则即使 composer require 成功也无法运行；版本需严格匹配 php 与框架要求，ide 补全需手动配置官方 stub。
composer require swoole/swoole 是无效操作
直接运行 composer require swoole/swoole 不会安装 Swoole 运行时能力，它只是个空壳包，仅声明了 "ext-swoole": "^5.0" 依赖。Composer 检查失败时抛出的错误（如 ext-swoole is missing）不是因为没装这个包，而是底层 PHP 扩展根本不存在。
- 真正起作用的是系统级扩展：必须通过
pecl install swoole或源码编译安装，并在php.ini中启用extension=swoole -
swoole/swoole包在 Composer 中只用于版本约束和 IDE 提示（部分旧版），2026 年主流项目已弃用该方式 - 若你执行后
php -m | grep swoole无输出，说明安装完全没生效——别调composer dump-autoload，去查pecl或phpize流程
装对版本比“装上”更重要
Swoole 扩展版本、PHP 版本、Laravel/Octane/超框架之间存在硬性兼容边界，错一个就启动失败或行为异常。
- PHP 8.0+ 才能用 Swoole v5.x；PHP 7.4 仅支持到 v4.8.x —— 查
php -v再决定装哪个分支 - Laravel Octane v2 要求 Swoole ^4.6；Octane v3 强制要求 ^5.0 —— 看清你
composer show laravel/octane的实际版本 - 运行
php --ri swoole，确认输出里有version => 5.1.4这类明确数字，而不是只看到模块名 - 不要加
--ignore-platform-req=ext-swoole掩盖问题，那只会让后续php artisan octane:start崩在 runtime
IDE 补全要手动配 stub，不是靠 composer
装了扩展，但 PHPStorm 或 VS Code 里 Swoole\Coroutine\run() 没提示？这不是 Composer 没装好，是 IDE 不认识 Swoole 的函数签名。
- 官方
swoole/ide-helper是 GitHub 仓库，不是 Composer 包：运行git clone https://github.com/swoole/ide-helper.git，然后把stubs/目录路径加进 IDE 的 Stub 设置 - VS Code + Intelephense：在工作区设置里写
"intelephense.stubs": ["./ide-helper/stubs"]，不是填"swoole"（那是极简内置 stub，漏掉协程通道、定时器等关键 API） - PHPStorm 需确保项目 Language Level ≥ 8.0，否则联合类型（如
string|int）提示会断
laravel-swoole 和 Octane 别混着用
两个方案都基于 Swoole，但生命周期、配置逻辑、路由加载机制完全不同。同时引入会导致服务启动失败、中间件重复执行、Session 丢失等静默故障。
-
swooletw/laravel-swoole是 Laravel 5–8 时代的封装，靠php artisan swoole:http start启动独立 HTTP server，需手动处理APP_URL、SWOOLE_HTTP_HOST等环境变量 -
laravel/octane是 Laravel 8.5+ 官方方案，统一抽象 Swoole/RoadRunner，命令是php artisan octane:start，自动接管请求生命周期，不兼容laravel-swoole的配置文件 - 检查
config/swoole_http.php和config/octane.php是否共存；运行php artisan package:discover后看是否列出了两个 Swoole 相关服务提供者
composer require 成功了，却连 new Swoole\Http\Server 都报错」，问题一定出在 php.ini 或 pecl 这一层。 
