Swoole安装后无法加载so文件的原因-Swoole-PHP中文网

php cli与web环境使用不同php.ini，需分别在两者配置文件中添加extension=swoole（windows）或extension=swoole.so（linux/macos），并确保版本、ts/nts、架构、依赖库及权限完全匹配。

swoole安装后无法加载so文件的原因

PHP CLI 和 Web 环境用了不同的 php.ini

你执行 php -m | findstr swoole 没输出，但浏览器打开 info.php 却能看到 Swoole 模块——这说明 CLI 和 Apache/Nginx 加载的是两套配置。常见于 phpEnv、XAMPP、Docker 或多版本 PHP 共存环境。

必须分别检查：

php --ini 查 “Loaded Configuration File” 路径（CLI 用的 ini）
<?php phpinfo(); ?> 页面里搜 “Loaded Configuration File”（Web 用的 ini）
两个文件都要加 extension=swoole（Windows）或 extension=swoole.so（Linux/macOS）

Windows 下误用了 .so 文件或不匹配的 .dll

phpEnv、WAMP、XAMPP 等 Windows 集成环境只认 .dll，且必须严格匹配三项：PHP 主版本（如 8.0）、线程模型（ts 表示 Thread Safe，nts 表示 Non-Thread Safe）、架构（x64 或 x86）。

典型错误包括：

Swoole 6.1.1

Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。

下载

从 Linux 项目里直接复制 swoole.so 过来 —— 它在 Windows 上根本无法加载
下载了 PHP 8.1 的 php_swoole.dll，却用在 PHP 8.0 环境中
PHP 是 TS 模式（phpinfo 中 Thread Safety = enabled），却用了 nts 标识的 DLL
DLL 放进了错误目录，比如没放进 phpEnv 当前 PHP 版本的 ext/ 目录（如 D:\phpEnv\php\php-8.0.30\ext\）

Linux/macOS 下 so 文件依赖缺失或加载顺序错乱

即使 swoole.so 编译成功、路径正确、extension= 配置无误，仍可能报 Unable to load dynamic library，原因常是：

ldd /path/to/swoole.so | grep "not found" 显示缺 libssl.so.1.1、libnghttp2.so 等 —— 尤其启用 HTTP/2 或 OpenSSL 支持时
extension=swoole.so 写在 extension=sockets.so 之前，导致符号 php_sockets_le_socket 找不到（CentOS/RHEL 常见）
mysqlnd、sockets 等基础扩展由 /etc/php.d/*.ini 独立加载，而你的 swoole.so 配置写在主 php.ini 末尾，实际先于它们加载
SELinux 启用状态下拦截动态库加载（getenforce 返回 Enforcing 时可临时 setenforce 0 测试）

扩展名写法、路径和权限的硬性细节

看似简单，但极易因一个字符出错：

Windows 下写 extension=php_swoole.dll 或 extension="swoole.dll" → 错，必须是 extension=swoole（不带后缀，也不带引号）
Linux 下写 extension=/usr/lib/php/20220829/swoole.so → 对，但若路径含中文、空格或软链接断裂，也会静默失败
swoole.so 文件权限不是 644，比如是 600 或属主不匹配（Apache 用户无法读取）
extension_dir 配置值错误，或未取消注释（尤其某些 Docker 镜像默认注释掉该行）
php.ini 中有中文注释或 BOM 头，导致整行配置被跳过（可用 file -i php.ini 检查编码）

最麻烦的其实是“看起来都对，但就是不生效”——这时候要盯死三件事：当前进程到底加载了哪个 php.ini、那个 ini 里 extension 是否真被解析、对应 so/dll 文件是否能被 PHP 进程按路径定位并完成符号绑定。任何一环断开，class_exists('Swoole\Server') 就永远是 false。