PHP 8.3 必须使用 Swoole 5.1.x（如 5.1.5），因 4.8.13 不支持、5.0.x 未适配其 ZTS 和协程底层变更；需 CLI 与 FPM 双 php.ini 启用 extension=swoole（PECL）或 swoole.so（编译），并首行调用 Swoole\Runtime::enableCoroutine() 才能启用协程。
PHP 8.3 只能用 Swoole 5.1.x（如 5.1.5），装 swoole 4.8.13 或 5.0.x 都会失败或运行时报错，不是“不生效”，是根本加载不了类或直接段错误。
确认 PHP 8.3 和 Swoole 版本是否严格匹配
别信“差不多能用”。swoole 4.8.13 是最后一个支持 PHP 7.4 的版本，它在 PHP 8.3 上编译可能通过，但运行时 new Swoole\Http\Server 会报 Class not found；swoole 5.0.x 要求 PHP ≥ 8.0，但未适配 PHP 8.3 的 ZTS 和协程底层变更，已知存在 Segmentation fault 风险。当前（2026 年 8 月）最稳的是 swoole-5.1.5，官网明确标注支持 PHP 8.4，向下兼容 8.3。
执行以下三行命令交叉验证：
php -v<br>php-config --version<br>pecl list | grep swoole
php-config --version 输出的是编译时锁定的主版本号，比 php -v 更可靠——尤其当你服务器上共存多个 PHP 版本时。
立即学习“PHP免费学习笔记（深入）”；
Linux/macOS 下用 pecl 安装必须配齐系统依赖
缺依赖不会报错，而是静默跳过 --enable-openssl 或 --enable-http2，导致后续 WebSocket、HTTPS、gRPC 全部不可用。
- Ubuntu/Debian：
sudo apt install php-dev build-essential cmake autoconf libssl-dev - CentOS/RHEL/AlmaLinux：
sudo dnf install php-devel gcc gcc-c++ make cmake autoconf openssl-devel - macOS（Homebrew）：
brew install pcre2 cmake，若安装时报'pcre2.h' file not found，需手动软链：cp /opt/homebrew/Cellar/pcre2/*/include/pcre2.h /opt/homebrew/Cellar/php@8.3/*/include/php/ext/pcre/
然后用完整路径调用：/opt/homebrew/bin/phpize（macOS）或 /www/server/php/83/bin/phpize（宝塔），再执行：/opt/homebrew/bin/php -d extension_dir=$(php -r"print_r(get_cfg_var('extension_dir'));") -m | grep swoole 确认 CLI 是否加载成功。
FPM 模式下 extension 配置容易漏写或写错
PECL 安装后，extension=swoole.so 通常只自动写入 CLI 的 conf.d 目录（如 /etc/php/8.3/cli/conf.d/20-swoole.ini），FPM 的配置文件（如 /etc/php/8.3/fpm/conf.d/ 或宝塔的 /www/server/php/83/etc/php.ini）往往为空，导致 Web 请求里 phpinfo() 找不到 Swoole。
检查并确保两处都加了启用行：
- CLI 配置：通常是
/etc/php/8.3/cli/php.ini或/opt/homebrew/etc/php/8.3/php.ini - FPM 配置：宝塔是
/www/server/php/83/etc/php.ini，系统包管理器安装的是/etc/php/8.3/fpm/php.ini
注意写法差异：
PECL 安装新版后可能是 extension=swoole（无 .so 后缀），而手动编译的必须写 extension=swoole.so；写错会导致 PHP Warning: Module 'swoole' already loaded 或完全不加载。
改完必须「重启 PHP-FPM 进程」，不是重载（reload）——宝塔界面点「重启」，命令行用：sudo systemctl restart php8.3-fpm 或 service php-fpm-83 restart。
启用协程前必须调用 Swoole\Runtime::enableCoroutine()
PHP 8.3 + Swoole 5.1.x 默认不开启协程 Hook，所有 fopen、curl_exec、pdo_query 仍是同步阻塞的。不调用这句，你写的 Co::sleep(1) 会直接报 Call to undefined function Swoole\Coroutine\sleep()，或者 Co::httpGet 返回空。
调用时机很关键：
- 必须在
require或include任何业务代码之前执行 - 不能放在框架的中间件、控制器或路由回调里——那时事件循环已启动，Hook 失效
- CLI 脚本和 FPM 入口都要加，例如在 ThinkPHP 的
public/index.php顶部立即写：Swoole\Runtime::enableCoroutine();
验证是否生效：php --ri swoole 输出中必须包含 coroutine => enabled，且没有 Warning 提示 Hook 失败。
最容易被忽略的是：即使所有配置都对，只要没在入口第一行调用 Swoole\Runtime::enableCoroutine()，整个协程链路就形同虚设——它不像扩展加载那样有明显报错，而是静默退化为普通 PHP，直到压测时连接堆积、QPS 断崖下跌才暴露问题。
