必须用 pecl install swoole 安装，因 Swoole 是编译型扩展；需提前安装 php-dev、gcc、make 等构建工具；PHP 与 Swoole 版本须严格匹配；Docker 中必须设置 opcache.enable_cli=0；Alpine 需额外安装 openssl-dev 和 nghttp2-dev 并指定参数启用 SSL/HTTP2。
PHP 扩展安装必须用 pecl install swoole，不能只改 php.ini
很多人以为在 Dockerfile 里写一句 extension=swoole.so 就完事了，结果容器一跑就报 Class 'Swoole\Http\Server' not found。根本原因是：swoole 不是纯 PHP 文件，它是个编译型扩展，得先编译安装进 PHP 运行时环境。
正确做法是在构建镜像时调用 pecl install swoole，并确保对应版本的 PHP-dev 和构建工具已就位。常见错误是漏装 php-dev（Debian/Ubuntu 下叫 php<version>-dev</version>）或 gcc、make，导致 pecl 编译失败。
- Debian/Ubuntu 镜像中，先
apt-get update && apt-get install -y php-dev gcc make - Alpine 镜像中，改用
apk add --no-cache php<version>-dev gcc make autoconf</version> - 安装后务必加一句
docker-php-ext-enable swoole，否则php -m看不到它
PHP 版本和 Swoole 版本必须严格匹配
比如 PHP 8.2 用 pecl install swoole-5.1.2 没问题，但装 swoole-4.8.13 就会编译报错——老版本压根不支持 PHP 8.2 的 ZTS 变更和类型系统。反过来，PHP 7.4 强行装 swoole 5.x 也会挂掉。
查兼容性最稳的方式是翻官网的 Installation Matrix，或者直接运行：pecl search swoole 看哪些版本标了对应 PHP 版本号。
- PHP 8.0–8.3 推荐用
swoole-5.1.x或swoole-5.2.x - PHP 7.4 停留在
swoole-4.8.x最稳妥 - 别信“最新版最稳定”，swoole 主要版本迭代快，新特性常带 BC break
Docker 中禁用 opcache.enable_cli=true 是硬性要求
一旦开了 opcache.enable_cli=1（有些基础镜像默认开），Swoole 的协程调度器就会出问题：Swoole\Coroutine::create() 可能静默失败，HTTP 服务启动后收不到请求，或出现 Segmentation fault。这不是 bug，是 opcache 对 CLI 模式下动态加载的 C 扩展内存管理不兼容。
解决方案很简单：在 php.ini 或 conf.d/swoole.ini 里显式关掉它。
- 加一行
opcache.enable_cli=0，不要依赖注释掉的默认值 - 确认生效：进容器跑
php -i | grep opcache.enable_cli，输出必须是opcache.enable_cli => Off => Off - 这个配置必须在
swoole.so加载之后生效，顺序不对也白搭
Alpine 镜像里 swoole 默认不启用 SSL 和 HTTP2 支持
Alpine 默认用的是 musl libc，而 Swoole 的 SSL/H2 功能依赖 OpenSSL 和 nghttp2。如果没手动编译开启，Swoole\Http\Server 启动时设了 ssl => true 会直接报 SSL is not supported，连错误日志都懒得打。
想用 HTTPS 或 HTTP/2，必须在 pecl 安装前装好依赖，并传参指定：
- Alpine 先
apk add --no-cache openssl-dev nghttp2-dev - 再执行
pecl install -D WITH_OPENSSL_DIR=/usr/include/openssl swoole - 验证是否成功：
php --ri swoole输出里要有openssl => enabled和http2 => enabled
没配这一步，哪怕证书路径全对，Swoole\Http\Server 也只会安静地降级成 HTTP/1.1，连 warning 都不抛。
