PHP 8.3/8.4 必须使用 Swoole 5.1.x（如 5.1.5），因 4.x 不支持、5.0+ 要求 PHP ≥ 8.0；需分别配置 CLI 和 FPM 的 php.ini 启用 extension=swoole，并确保编译时启用 --enable-openssl 和 --enable-http2，最后用 php --ri swoole 验证协程是否真正启用。
PHP 8.3/8.4 必须用 Swoole 5.1.x，别碰 4.x
Swoole 4.8.13 是最后一个支持 PHP 7.4 的版本，在 PHP 8.3 或 8.4 上编译会失败或运行时报 Segmentation fault；装完看似成功，但执行 new Swoole\Http\Server 会直接报 Class not found。Swoole 5.0 起强制要求 PHP ≥ 8.0，而当前（2026 年 5 月）最稳的是 swoole-5.1.5，它已明确标注支持 PHP 8.4。
验证方式不是只看 php -v，而是必须运行：
php-config --version<br>pecl list | grep swoole
php-config --version 输出的是编译时主版本号，比 php -v 更可靠——尤其当系统存在多个 PHP 版本时。
CLI 和 FPM 的 php.ini 必须各自加 extension=swoole
宝塔、phpenv、源码编译等环境里，CLI 和 FPM 加载的是两套完全独立的配置文件。只改一个，必然出现「命令行能跑，网页报 Class not found」或反过来。这不是配置遗漏，是 PHP 运行机制决定的。
立即学习“PHP免费学习笔记（深入）”；
- 查 CLI 实际加载路径：
php --ini | grep "Loaded Configuration File" - 查 FPM 实际加载路径：在宝塔中是
/www/server/php/83/etc/php.ini（数字按实际 PHP 子目录替换）；在 phpenv 中是~/.phpenv/versions/8.3.0/etc/php.ini - 两个文件末尾都加同一行：
extension=swoole（PHP 8.0+ 不需要写.so后缀） - 改完 FPM 配置后必须重启服务：
bt restart php83或systemctl restart php-fpm
源码编译时 --enable-openssl 和 --enable-http2 不是可选项
漏掉这两个参数，swoole_http_server 构造函数会静默失败，swoole_websocket_server 握手通不过，错误日志里只有模糊的 Connection reset by peer，根本看不出是编译问题。
正确流程（以 PHP 8.3 为例）：
- 先装依赖：Ubuntu/Debian 执行
sudo apt install libssl-dev，CentOS/RHEL 执行sudo dnf install openssl-devel - 进入 Swoole 源码目录后，调用对应版本的工具：
~/.phpenv/versions/8.3.0/bin/phpize（phpenv）或/www/server/php/83/bin/phpize（宝塔） - configure 命令必须带全路径和开关：
./configure --with-php-config=/www/server/php/83/bin/php-config --enable-openssl --enable-http2 - 编译安装后，记下输出的扩展路径，例如：
/www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/，确保php.ini中extension_dir指向它
协程功能需显式启用，且验证不能只靠 php -m
php -m | grep swoole 只说明模块名在列表里，不代表真正加载成功或协程可用。真正可靠的验证命令是：
php --ri swoole
输出中必须同时满足：
enabled => trueenable coroutine => true-
version => 5.1.5（或你安装的实际版本）
ThinkPHP 等框架还要求手动调用 Swoole\Runtime::enableCoroutine()，否则数据库、Redis 等 I/O 仍会阻塞协程调度——这个调用点容易被忽略，尤其在自定义启动脚本中。
