新手安装Swoole应优先使用宝塔面板「软件商店」一键安装，仅当商店无对应版本或需特定功能（如HTTPS/WSS）时才手动编译；必须严格匹配PHP路径、启用--enable-openssl和--enable-http2参数，并在CLI与FPM的php.ini中均添加extension=swoole.so后重启PHP服务。
直接说结论：新手装 Swoole，95% 的情况该用宝塔面板「软件商店」一键安装，而不是开终端敲命令；只要 PHP 版本对得上、点对按钮、重启到位，基本一次成功。
宝塔面板里怎么找并安装 Swoole 扩展
别一上来就 ssh 登录、别急着 pecl install。先确认你用的是宝塔，并且 PHP 8.0（或 7.4/8.1）已通过面板安装好：
- 登录宝塔 → 「软件商店」→ 找到你当前站点用的 PHP 版本（比如 PHP 80）→ 点「设置」
- 切换到「安装扩展」标签页 → 搜索框输入
swoole - 如果列表里有
swoole4或swoole5，直接点「安装」→ 安装完点「重启 PHP」（注意是「重启」，不是「重载」） - 验证：在终端执行
php --ri swoole，能看到版本号和特性列表就成功了
为什么 php --ri swoole 报错“not found”
这几乎全是配置文件没改对或没生效导致的。宝塔中 CLI 和 FPM 用两套 php.ini：
- FPM 加载的是：
/www/server/php/80/etc/php.ini - CLI（命令行）加载的是：
/www/server/php/80/bin/php.ini - 两个文件末尾都必须加这一行：
extension=swoole.so - 只改一个、漏改一个，
php -m和php --ri swoole就会表现不一致 - 改完配置后，FPM 必须「重启 PHP 服务」；CLI 不需要重启，但要用完整路径验证：
/www/server/php/80/bin/php --ri swoole
什么时候必须手动编译？怎么避免翻车
只有两种情况才需要自己编译：软件商店里搜不到你要的 Swoole 版本（比如要 swoole-5.1.5），或者你明确知道当前预编译包缺 --enable-openssl 导致 HTTPS/WSS 失败。
立即学习“PHP免费学习笔记（深入）”；
- 第一步永远是确认路径：
/www/server/php/80/bin/phpize（数字 80 必须和你实际 PHP 版本一致） -
./configure时必须带完整--with-php-config路径：--with-php-config=/www/server/php/80/bin/php-config - 必须加这两个参数：
--enable-openssl --enable-http2，否则swoole_http_server、WebSocket over HTTPS 全部不可用 - 编译完成后终端会输出安装路径，比如：
Installing shared extensions: /www/server/php/80/lib/php/extensions/no-debug-non-zts-20200930/—— 这个目录下必须有swoole.so文件，再往php.ini里写extension=swoole.so才有意义
PECL 安装为啥不推荐给新手
PECL 看似简单，但新手容易踩三个隐性坑：
-
pecl install swoole默认不启用openssl和http2，装完发现swoole_http_server函数不存在，还得重装 - 它会把
extension=swoole写进系统默认的php.ini，但宝塔的 FPM 并不读那个文件，结果phpinfo()里看不到模块 - PECL 安装的扩展名是
swoole（无 .so），而源码编译出来是swoole.so；混用会导致扩展加载失败，报Unable to load dynamic library 'swoole'
真正容易被忽略的是：Swoole 功能是否可用，不能只看 php -m | grep swoole 显示出来了，得实际跑一个 swoole_http_server 实例，用 curl 测试 HTTPS 接口，才能确认 --enable-openssl 生效了——很多“安装成功”的人卡在这一步。
