应优先通过宝塔软件商店安装Swoole扩展；若失败，则需严格匹配PHP路径、同时配置CLI与FPM的php.ini、启用--enable-openssl和--enable-http2参数，并分环境验证php --ri swoole。
宝塔面板里点“安装Swoole扩展”后页面提示成功，但实际运行PHP项目时仍报错Class 'Swoole\Http\Server' not found，或php --ri swoole返回“Extension 'swoole' not present”，说明扩展根本没加载进运行环境。这不是按钮没点对，而是背后多个环节存在隐性断点。
先确认失败类型：是根本没装上，还是装上了但没生效
打开宝塔终端，执行以下命令：
【/www/server/php/80/bin/php --ri swoole】（把80换成你实际用的PHP子目录号，比如74、81）
如果返回“Extension 'swoole' not present”，说明.so文件压根没生成或路径不对；如果返回一堆信息但写着enabled => false，或者版本号明显旧（如2.2.0），说明扩展已存在但被禁用或版本冲突。
这一步必须做，跳过它直接改配置等于蒙眼修电路。
检查编译路径是否完全匹配
手动编译失败90%出在这里——phpize和php-config路径只要差一个字符，swoole.so就会被扔进错误目录。
第一步：查清你网站实际用的PHP路径。进宝塔 → 网站 → 你的站点 → PHP版本，右上角显示“PHP-80”，不代表就一定是/www/server/php/80；点击右侧“设置”→“配置文件”，看顶部注释行写的实际路径。
第二步：用这个路径执行phpize，例如：/www/server/php/80/bin/phpize
第三步：configure时必须用完整php-config路径：./configure --with-php-config=/www/server/php/80/bin/php-config --enable-openssl --enable-http2
注意：不能写成php-config-8.0，也不能漏掉/bin/；CentOS系统还必须提前装openssl-devel，否则--enable-openssl会静默失效，后续WebSocket连接直接被拒绝。
两个php.ini都要改，且位置完全不同
宝塔里CLI和FPM用的是两套独立配置，只改一个，必然一半环境认、一半不认。
方法一：快速注入（推荐）
CLI配置路径：echo "extension=swoole.so" >> /www/server/php/80/bin/php.ini
FPM配置路径：echo "extension=swoole.so" >> /www/server/php/80/etc/php.ini
方法二：手动编辑（适合需加参数的场景）
用宝塔文件管理器打开上述两个文件，在末尾空行添加extension=swoole.so，保存。
注意：如果用PECL装的是Swoole 5.0+，extension写法可能是extension=swoole（无.so后缀），写错直接加载失败。
验证必须分环境跑，不能只信php -m
php -m | grep swoole只能说明模块名在列表里，不能证明能用。
第一步：验证CLI环境：/www/server/php/80/bin/php --ri swoole
第二步：验证Web环境：新建一个info.php文件，内容为<?php phpinfo(); ?>，浏览器访问，搜索“swoole”，确认有enabled状态和版本号。
第三步：如果CLI正常但Web不显示，说明FPM的php.ini没生效，重点检查/www/server/php/80/etc/php-fpm.d/www.conf里有没有php_admin_value[extension]覆盖了主配置。
排除Swoole Loader冲突
某些加密项目（如榜店商城v4）强制依赖swoole_loader_20_php72.so，它和原生swoole.so互斥。
执行php -m，如果同时看到swoole和swoole_loader，立刻删掉其中一个——优先保留loader，因为加密项目启动时会先校验loader，再加载业务代码。
删loader命令：rm -f /www/server/php/80/lib/php/extensions/no-debug-non-zts-20200930/swoole.so
删原生swoole命令：rm -f /www/server/php/80/lib/php/extensions/no-debug-non-zts-20200930/swoole_loader*.so
删完必须重启PHP服务，否则残留进程仍会报Module 'swoole' already loaded。
