PHP CLI 和 FPM 的 Swoole 扩展需分别配置独立 php.ini，否则出现类找不到；须检查并统一 extension=swoole 配置，避免重复加载或混用 loader/版本，编译时务必匹配对应 php-config 路径及 ABI 目录。
PHP CLI 和 FPM 的 swoole 扩展必须分别配置
宝塔、phpenv 或源码编译环境里，CLI 和 FPM 加载的是两套完全独立的 php.ini。只改其中一个，必然出现「命令行能跑，网页报 Class not found」或反过来。这不是配置遗漏，是 PHP 运行机制决定的。
查 CLI 实际加载路径：php --ini | grep "Loaded Configuration File"
查 FPM 实际加载路径：宝塔中通常是 /www/server/php/83/etc/php.ini（数字按实际 PHP 子目录替换）；phpenv 中是 ~/.phpenv/versions/8.3.0/etc/php.ini
- 两个文件末尾都加同一行：
extension=swoole（PHP 8.0+ 不需要写.so后缀） - 改完 FPM 配置后必须重启服务：
bt restart php83或systemctl restart php-fpm - 装完别急着测代码，先运行
php --ri swoole和php-fpm -m | grep swoole分别验证
swoole.so 被重复加载导致 Module 'swoole' already loaded
这个错误不是版本冲突，而是扩展被多次声明。常见于：
- php.ini 里写了两次
extension=swoole - 通过
zend_extension错误地加载了swoole_loader（比如禾匠系项目自带的swoole_loader_20_php72.so） - 宝塔软件商店自动启用了旧版 swoole，又手动编译装了新版，两者共存
解决方法：
- 用
grep -r "extension=swoole\|zend_extension" /www/server/php/扫描所有 php.ini 及子目录下的 ini 文件 - 确认
swoole_loader和原生swoole绝对不能共存——删掉 loader 相关行，或彻底卸载 loader - 如果用的是加密项目（如榜店商城 v4），优先保留 loader，放弃原生 swoole 扩展
PHP 8.2+ 下混用 Swoole 4.x 和 5.x 会直接报错
Swoole 4.8.13 是最后一个支持 PHP 8.2 的 4.x 版本；Swoole 5.0+ 强制要求 PHP ≥ 8.0，但 5.1.5 才真正稳定适配 PHP 8.4。混用会导致：
立即学习“PHP免费学习笔记（深入）”；
-
new Swoole\Http\Server(..., true)报Fatal error: Uncaught Error: Call to undefined method（5.x 移除了第三个$ssl参数） -
Co::getCid()在非协程环境返回0（4.8.10+ 和 5.x 行为变更，旧代码可能误判协程上下文） -
log_level默认值从5变成2，关键调试日志被静默丢弃
判断当前实际版本：php --ri swoole | grep version，别信 composer.json 里写的 "swoole/swoole": "^4.5" —— 它不保证运行时行为一致。
多个 PHP 版本共存时，php-config 路径容易搞错
源码编译 swoole 时，./configure 必须指定对应版本的 php-config，否则扩展会被编译进错误的 ABI 槽位，导致 undefined symbol 错误。
验证方式不是 php -v，而是：php-config --version（输出编译时主版本号，比 php -v 更可靠）
- phpenv 用户：用
~/.phpenv/versions/8.3.0/bin/php-config，别用全局php-config - 宝塔用户：路径是
/www/server/php/83/bin/php-config，注意数字和实际子目录一致 - 漏掉
--enable-openssl或--enable-http2，swoole_http_server构造函数会静默失败，日志里只有模糊的Connection reset by peer
最易被忽略的一点：不同 PHP 版本的扩展目录（no-debug-non-zts-20230831 这类）完全不同，复制错路径会导致扩展根本加载不起来，连错误提示都没有。
