必须源码编译并显式启用 --enable-swoole-thread，PECL 安装默认不开启且无法后续补开，因其构建不触发线程相关头文件和链接逻辑，生成的 swoole.so 不含 SWOOLE_THREAD 符号，即使 PHP 启用 ZTS，运行时传 SWOOLE_THREAD 仍报“Unknown server mode”。
必须源码编译并显式启用 --enable-swoole-thread，PECL 安装默认不开启，也无法后续补开。
为什么 PECL 安装不能用多线程模式
PECL 构建时不会自动添加线程支持开关，生成的 swoole.so 不含 SWOOLE_THREAD 符号。即使 PHP 已启用 ZTS，运行时调用 new Swoole\Http\Server(..., SWOOLE_THREAD) 仍会直接报错：Fatal error: Uncaught Error: Unknown server mode。
- PECL 安装本质是预编译二进制或无参数的 configure，不触发线程相关头文件和链接逻辑
-
php -m | grep swoole看不到线程能力提示，php --ri swoole里也不会显示thread support => enabled - 别指望改 php.ini 或 reload 扩展能“打开”这个功能——它在 .so 文件编译那一刻就固定了
源码编译启用线程支持的实操步骤
以 v6.0.0 为例（低于 v6.0-alpha 的版本根本不支持）：
Swoole 6.1.1
下载
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
- 先确认 PHP 是 ZTS 模式：
php -i | grep "Thread Safety"输出必须为enabled；否则编译会失败或运行时报Swoole extension is not compiled with thread safety support - 克隆指定 tag 源码：
git clone --branch v6.0.0 https://github.com/swoole/swoole-src.git - 进入目录后执行：
phpize && ./configure --enable-swoole-thread --enable-openssl --enable-http2（--enable-swoole-thread是唯一必需项，其他按需加） -
make -j$(nproc) && sudo make install，完成后检查php --ri swoole是否出现thread support => enabled - 务必禁用
pthreads扩展：若 php.ini 中有extension=pthreads.so，注释掉并重启 PHP，否则加载失败
常见错误现象与对应原因
编译或运行阶段出错，基本就这三类：
-
configure: error: pthread.h not found→ 缺少系统级线程开发包，Ubuntu/Debian 装libpthread-stubs0-dev，CentOS/RHEL 装glibc-devel - 启动 Server 时报
Segmentation fault→ PHP ZTS 未启用，或同时加载了pthreads扩展 -
worker_num设为 4 却只看到 1 个线程在跑 → 服务启动时没传SWOOLE_THREAD标志，比如写成SWOOLE_BASE或漏写第三个参数，此时worker_num仍按进程数解释，但实际走的是单线程逻辑
线程支持不是“开关式功能”，它从编译、ZTS、扩展共存关系到运行时标志层层咬合；漏掉任一环，SWOOLE_THREAD 都只是个无效常量。别跳过 php --ri swoole 的验证步骤——那是唯一能确认你真拿到线程能力的地方。
