PHP CLI与Web环境使用不同php.ini，需分别在两者配置文件中添加extension=swoole（Windows）或extension=swoole.so（Linux/macOS），并确保版本、TS/NTS、架构、依赖库及权限完全匹配。
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。
