判断Swoole版本兼容性需核对php --ri swoole的version行，验证协程组件存在性及行为一致性；4.8.x起移除Http\Server同步回调，5.0.x废弃Process非静态start方法；功能探测应使用class_exists('Swoole\Coroutine\MySQL')而非extension_loaded；PHP 8.2+下4.8.13为最后支持的4.x版本，5.x要求PHP 8.0+；HTTP Server构造参数签名变更，ssl配置改用set(['ssl'=>true])；on('start')中禁用阻塞函数；I/O操作须用协程API；log_level默认值从5变为2；Co::getCid()在非协程环境返回0，应改用Co::getContext()；Timer回调需显式go包装；Redis/MySQL connect默认超时改为0.5秒；混合部署时需分离autoload并禁用opcache.enable_cli；tcp_nodelay默认关闭导致小包延迟升高，需手动启用。
怎么判断当前 Swoole 版本是否兼容你的代码
直接看 php --ri swoole 输出的 version 行，比对你的核心依赖（比如协程 MySQL 客户端、Swoole\Coroutine\Http\Client）是否在该版本中存在且行为一致。4.8.x 起移除了 Swoole\Http\Server 的同步回调模式，5.0.x 彻底废弃 Swoole\Process 的非静态 start 方法——这些不是警告，是运行时直接报 Fatal error: Uncaught Error: Call to undefined method。
- 用
class_exists('Swoole\Coroutine\MySQL')替代extension_loaded('swoole')做功能探测 - 别信 composer.json 里写的
"swoole/swoole": "^4.5"，实际要测Swoole\Coroutine::create()是否能正常调度 - PHP 8.2+ 下，Swoole 4.8.13 是最后一个支持的 4.x 版本；5.0.x 要求最低 PHP 8.0
升级到 Swoole 5.x 后 HTTP Server 启动就失败？
不是配置写错了，是 Swoole\Http\Server 的构造参数签名变了：5.x 移除了第三个 $ssl 布尔参数，改用 set(['ssl' => true]) 统一配置。同时 on('start') 回调里不能再调 gethostbyname() 这类阻塞函数——协程环境里它会卡死整个 reactor 线程。
- 旧写法：
new Swoole\Http\Server('0.0.0.0', 9501, SWOOLE_BASE, true) - 新写法：
new Swoole\Http\Server('0.0.0.0', 9501, SWOOLE_BASE); $server->set(['ssl' => true]) -
on('request')中所有 I/O 操作必须走协程 API，比如用Swoole\Coroutine\Http\Client替代file_get_contents() - 日志路径配置从
log_file改为log_file仍可用，但log_level默认值从 5 变成 2（只报 warning 及以上）
协程上下文丢失：为什么 go(function () { echo Co::getCid(); }) 打印 0
这是 4.8.10+ 和 5.x 的关键行为变更：Co::getCid() 在非协程环境（比如主进程、信号回调、定时器回调外层）一律返回 0，不再伪造 cid。以前靠这个“猜”是否在协程里做逻辑分支的代码，现在会直接失效。
- 别再用
Co::getCid() > 0判断协程上下文，改用Co::getContext()—— 它在非协程环境返回null，更可靠 - 定时器回调（
Timer::tick()）默认不在协程中执行，需显式包装：Timer::tick(1000, function () { go(fn() => doSomething()); }) - Redis、MySQL 协程客户端的
connect()方法在 5.x 中默认超时从 -1（无限）改为 0.5 秒，容易触发Connection refused而不是等待
PHP-FPM 和 Swoole 混合部署时 autoload 冲突怎么破
Composer 自动加载器在 Swoole 长生命周期下会缓存类定义，但 PHP-FPM 请求结束就销毁——如果两个环境共用同一份 vendor/autoload.php，Swoole 进程 reload 后可能加载到旧版类文件，而 FPM 还在用新版，导致 Declaration of X must be compatible with Y。
- 给 Swoole 启动脚本单独生成 autoloader：
composer dump-autoload --classmap-authoritative，避免 runtime 类查找歧义 - 禁用 opcache 的
opcache.enable_cli=1（CLI 模式下开启 opcache 会导致 Swoole reload 后类定义不更新） - 不要在
onWorkerStart里 require 或 include 全局配置文件，改用onWorkerStart+Co::sleep(0)触发协程调度后再加载，确保加载发生在协程上下文中
版本差异最麻烦的从来不是 API 删除，而是那些没报错、只是行为变慢或偶尔丢数据的隐性变化——比如 5.x 默认关闭了 tcp_nodelay，HTTP/1.1 长连接下小包延迟明显升高，得手动 set(['tcp_nodelay' => true]) 才能还原。
