先看加载顺序，swoole.so需在mysqlnd.so、sockets.so之后加载，否则报undefined symbol；CLI与FPM配置路径不同需分别配置；Windows下须严格匹配PHP版本、TS/NTS、VC编译器及架构。

php --ri swoole 有输出但服务启动失败，先看加载顺序

扩展“安装成功”不等于“能用”，常见原因是依赖扩展（如 mysqlnd、sockets）加载晚于 swoole.so。Linux 下宝塔或源码编译环境常把 mysqlnd.ini 放在 /etc/php.d/ 目录，而该目录的 ini 文件是在 php.ini 之后加载的，导致 swoole.so 找不到 mysqlnd_find_charset_nr 符号。

• 运行 php --ini 确认实际生效的配置路径
• 检查 /etc/php.d/ 下是否有 mysqlnd.ini、sockets.ini 等文件
• 要么删掉这些 ini 文件，要么把 extension=mysqlnd.so 和 extension=sockets.so 显式加到 php.ini 中 extension=swoole.so 的前面
• 改完后必须重启 php-fpm 或重载 PHP 配置，不能只重启 Web 服务

报错含 “undefined symbol” 或 “找不到模块”，重点查 ABI 兼容性

Windows 下尤其高发，错误如 PHP Warning: Unable to load dynamic library 'php_swoole.dll' (0x8007007E)，本质是 DLL 与当前 PHP 运行时 ABI 不匹配。

Swoole 6.1.1

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

下载

• 执行 php -v 看主版本（如 8.1），Swoole 必须严格对应（8.1 不能用 8.2 编译的 DLL）
• 执行 php -i | findstr "Thread Safety" 确认是 enabled（TS）还是 disabled（NTS）——Apache 用 TS，CLI/FPM 通常用 NTS
• 执行 php -i | findstr "Compiler" 看 VC 版本（VC16 对应 PHP 7.4–8.1，VC17 对应 8.2+）
• 执行 echo %PROCESSOR_ARCHITECTURE% 确认是 AMD64 还是 x86，必须与 PHP 二进制一致
• 下载 DLL 时务必按 swoole-php-{PHP_VERSION}-{VC_VERSION}-{ARCH}-{TS_OR_NTS}.zip 命名规则匹配

服务启动时报 “Swoole\Process::__construct() expects at most 3 parameters, 4 given”

这是典型的 Swoole 版本不兼容问题。旧版（如 2.x/3.x）构造函数参数数量与新版（4.5+）不同，框架（如 EasySwoole）代码调用方式已适配新版本，但服务器上装的是低版本 Swoole。

• 运行 php --ri swoole | findstr "Version" 查实际版本（别信宝塔面板显示的“已安装”）
• 确认项目依赖要求的最低 Swoole 版本（查看 composer.json 或文档）
• 宝塔自带的 Swoole 扩展往往版本陈旧（如 2.2），建议卸载后手动安装对应版本的 swoole.so 或 swoole_loader_*.so
• 注意：多个 extension=swoole.so 行会导致 Module 'swoole' already loaded 警告，删掉重复项

CLI 和 FPM 使用不同 php.ini，导致扩展启用不一致

你用 php -m 看到 swoole，但用 php-fpm 启动服务却报 class not found，大概率是两个环境加载了不同的配置文件。

• CLI 下执行 php --ini 查 Loaded Configuration File
• FPM 下建个 info.php 输出 phpinfo()，搜索 “Loaded Configuration File”
• 两者路径不一致时，必须分别在对应 php.ini 中添加 extension=swoole.so
• 若启用命名空间（use_namespace => 1），代码中必须写 \Swoole\Server，不能写 Swoole\Server

最麻烦的不是找不到错，而是错不在你写的代码里——它藏在 PHP 运行时环境的缝隙里：加载顺序、ABI 匹配、配置文件分裂、版本语义差异。每一步验证都得动手跑命令，不能靠“应该没问题”跳过。