必须确保swoole版本与php主版本、子版本、线程模型（nts/zts）、zend扩展api编号四者严格匹配；否则extension加载失败、php --ri swoole报“not found”或php服务启动异常。
在宝塔面板中安装Swoole扩展时，必须确保Swoole版本与PHP主版本、子版本、线程模型（NTS/ZTS）、Zend扩展API编号（如20200930）四者严格匹配，任意一项错配都会导致extension加载失败、php --ri swoole报“not found”或PHP服务启动异常。
查清你当前PHP的底层标识
登录宝塔 → 打开「终端」→ 执行以下命令：
php -v
注意输出末尾括号里的内容，例如 PHP 8.0.30 (cli) (built: Jun 12 2026 10:15:22) (NTS) —— 这里“8.0”是主版本，“30”是子版本，“NTS”代表非线程安全模式，这是后续下载.so文件的核心依据。
php-config --version
确认php-config输出的确实是8.0.x，避免误用PHP 7.4或8.1的工具链。
php-config --extension-dir
这条命令会直接返回Swoole.so最终要存放的目录路径，例如 /www/server/php/80/lib/php/extensions/no-debug-non-zts-20200930/ —— 路径末尾的 20200930 就是Zend扩展API编号，它由PHP 8.0编译时生成，不可更改，所有匹配的Swoole扩展必须对应这个编号。
软件商店安装：自动匹配但有局限
宝塔软件商店里的Swoole扩展是预编译好的二进制包，已按PHP子版本（如PHP 80）打包，点击安装即完成路径绑定和php.ini写入。
适用场景：仅需基础Swoole功能（协程、TCP/UDP Server），且商店列表中存在对应项（如“Swoole4”或“Swoole5”）。
不适用场景：需要swoole-5.1.5这类新版、需启用--enable-http2/--enable-coroutine等高级特性、或项目明确要求特定小版本（如5.0.3而非5.0.0）。
操作路径：软件商店 → 找到PHP 80 → 设置 → 安装扩展 → 搜索swoole → 点安装 → 点「重启 PHP」（不是重载）。
手动编译安装：精准可控但步骤严苛
当你必须使用特定Swoole版本（如5.1.5）或启用HTTP/2支持时，源码编译是唯一选择。成败关键在于三处路径和两个参数。
第一步：进入源码目录后，立即执行
/www/server/php/80/bin/phpize
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
注意：数字“80”必须与你实际PHP子目录名完全一致；若写成/phpize或/phpize-8.0，生成的config.m4将指向错误PHP环境，后续全盘作废。
第二步：配置编译参数
./configure --with-php-config=/www/server/php/80/bin/php-config --enable-openssl --enable-http2
漏掉--enable-openssl会导致WebSocket over HTTPS失效；漏掉--enable-http2会使Swoole\Http\Server无法处理HTTP/2请求，运行时报Call to undefined function swoole_http_server()；PHP 8.5+还必须加--enable-coroutine，否则Swoole\Coroutine::sleep()直接报not available。
第三步：编译并安装
make && make install
成功后终端会输出Installing shared extensions: /www/server/php/80/lib/php/extensions/no-debug-non-zts-20200930/——请立刻复制该路径，后面改php.ini时extension路径必须与之严格对应。
双php.ini同步配置：最容易被忽略的致命环节
宝塔中PHP CLI和PHP-FPM加载的是两套完全独立的配置文件，只改一个，另一个必然失效。
方法一：分别追加extension指令
向FPM配置写入：
echo "extension=swoole.so" >> /www/server/php/80/etc/php.ini
向CLI配置写入：
echo "extension=swoole.so" >> /www/server/php/80/bin/php.ini
注意：PECL安装新版后可能是extension=swoole（无.so后缀），务必根据实际生成的文件名填写。
方法二：验证是否生效
执行 /www/server/php/80/bin/php --ri swoole —— 这是唯一可信验证方式；php -m | grep swoole只能说明模块名在列表里，不能证明.so已正确加载。
若报错“not found”，90%是因为只改了其中一个php.ini。此时必须检查两个文件末尾是否都存在extension=swoole.so，且路径下确实存在该so文件。
