直接看php --ri swoole的version行即可定位大版本，再对照关键变更点调整代码；4.8.x起移除Http\Server同步回调、4.10.x起Co::getCid()非协程环境返回0、5.0.x废弃Process非静态start方法，PHP 7.4最高支持4.8.13，8.3/8.4必须用5.1.x，I/O操作须全协程化，SSL配置改用set(['ssl'=>true])，定时器回调需显式go包装。
直接看 php --ri swoole 输出的 version 行，就能快速定位当前版本所属大版本（如 4.8.x、4.10.x），再对照关键变更点判断是否需调整代码。Swoole 4.x 是稳定主力分支，但内部跨度大——4.2.x 起全面协程化，4.8.x 开始清理旧接口，4.10.x 进一步收紧行为一致性。升级不是“换新版就行”，而是要匹配 PHP 版本、重写阻塞调用、校验协程组件可用性。
重点关注兼容性断点
这些不是警告，是运行时直接 Fatal Error：
-
4.8.x 起移除
Swoole\Http\Server同步回调模式：旧写法on('request', function ($req, $resp) { file_get_contents(...); })会崩溃，必须改用Swoole\Coroutine\Http\Client或Co::readFile -
4.10.x 起
Co::getCid()在非协程环境返回 0：比如定时器外层、信号回调里调用，不再隐式创建协程上下文，应改用Co::getContext()判断是否存在有效上下文 -
5.0.x 已废弃
Swoole\Process::start()非静态方法：必须改为Swoole\Process::start()（静态调用），否则报Call to undefined method
PHP 版本与 Swoole 4.x 的绑定关系
别只看 composer.json 声明，实际运行依赖底层 ABI 兼容：
Swoole 6.1.1
下载
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
-
PHP 7.4 最高支持到 4.8.13：装更高版 4.x 会编译失败或运行时报
Segmentation fault -
PHP 8.0–8.2 推荐用 4.10.x 系列（如 4.10.6）：兼顾新特性与稳定性，
log_level默认值已从 5 降为 2，注意日志级别变化 -
PHP 8.3/8.4 必须跳过 4.x，直接上 5.1.x（如 5.1.5）：4.x 源码未适配 PHP 8.3+ 的 ZendVM 变更，即使编译成功，
new Swoole\Http\Server也会 Class not found
协程安全改造实操要点
不是加个 go() 就完事，关键是 I/O 调用链全协程化：
-
所有网络请求必须走协程客户端：
file_get_contents、cURL（未 Hook）、mysqli_connect全部禁用；改用Swoole\Coroutine\Http\Client、Swoole\Coroutine\MySQL、Swoole\Coroutine\Redis -
文件操作不能用
fopen/file_put_contents：改用Co::readFile/Co::writeFile，它们默认启用协程调度 -
SSL 配置方式统一：4.8+ 已弃用构造函数第三个布尔参数，改用
$server->set(['ssl' => true])，且编译时必须带--enable-openssl -
定时器回调需显式协程包裹：旧写法
Timer::after(1000, function () { ... })在 4.10+ 中可能丢失上下文，应写成Timer::after(1000, function () { go(function () { ... }); })
升级前必做三件事
避免上线后才发现问题：
-
用
class_exists('Swoole\Coroutine\MySQL')替代extension_loaded('swoole')：后者只说明扩展加载了，前者才能确认你依赖的核心协程组件真实可用 -
检查 CLI 和 FPM 的 php.ini 是否都启用了 swoole：宝塔用户路径通常是
/www/server/php/xx/etc/php.ini，phpenv 用户在~/.phpenv/versions/xx.x.x/etc/php.ini，改完必须重启服务 - 混合部署时分离 autoload 并禁用 opcache.enable_cli：防止 CLI 启动脚本和 Web 请求共享 opcode 缓存导致协程状态污染
