pecl install swoole是唯一可靠安装方式，因swoole为编译型C扩展，仅改php.ini加extension=swoole.so必然失败，典型错误是Class 'Swoole\Http\Server' not found；必须先装php-dev、gcc等构建工具，再pecl安装并docker-php-ext-enable，且PHP与Swoole版本须严格匹配，同时Docker中需设opcache.enable_cli=0并确保位置正确，Alpine还需额外安装openssl-dev和nghttp2-dev并启用SSL/HTTP2。
pecl install swoole 是唯一可靠安装方式
直接在 php.ini 里加 extension=swoole.so 必然失败，因为 swoole 是 C 扩展，必须编译加载。容器启动时找不到符号，Class 'Swoole\Http\Server' not found 就是典型表现。
正确流程是：先装构建依赖，再用 pecl install 编译，最后启用：
- Debian/Ubuntu 镜像：
apt-get update && apt-get install -y php-dev gcc make autoconf - Alpine 镜像：
apk add --no-cache php<version>-dev gcc make autoconf</version>（注意替换<version></version>，如php82-dev） - 执行
pecl install swoole（推荐显式指定版本，如pecl install swoole-5.1.2） - 必须跟一句
docker-php-ext-enable swoole，否则php -m看不到
PHP 与 Swoole 版本不匹配会编译失败
PHP 8.2 装 swoole-4.8.13 直接报错；PHP 7.4 强上 swoole-5.2.0 同样挂掉。这不是配置问题，是 ZTS、类型系统、内存模型等底层变更导致的硬性不兼容。
验证方法很简单：
- 进容器跑
pecl search swoole，看输出里哪些版本标了你的 PHP 版本号 - 查官网 Installation Matrix（比文档更准）
- 生产环境建议锁定组合：PHP 8.2 +
swoole-5.1.2，PHP 7.4 +swoole-4.8.13
opcache.enable_cli=0 是强制要求
很多基础镜像默认开启 opcache.enable_cli=1，这会导致 Swoole\Coroutine::create() 静默失效、HTTP 服务无法响应、甚至 Segmentation fault。这不是 bug，是 opcache 对 CLI 模式下动态扩展的内存管理冲突。
必须显式关闭，且顺序不能错：
- 在
php.ini或/usr/local/etc/php/conf.d/swoole.ini里加一行：opcache.enable_cli=0 - 这一行要放在
extension=swoole.so加载之后（否则不生效） - 验证命令：
php -i | grep opcache.enable_cli，输出必须是Off => Off
Alpine 镜像需额外处理 SSL 和 HTTP2
Alpine 默认不带 OpenSSL 和 nghttp2 的 dev 包，pecl install swoole 会跳过 SSL/HTTP2 支持，导致 Swoole\Http\Client 或 HTTPS 服务不可用。
补全步骤：
- Alpine 下先装：
apk add --no-cache openssl-dev nghttp2-dev - 再装 swoole 时加参数：
pecl install swoole -DENABLE_SSL=1 -DENABLE_HTTP2=1 - 如果用
install-php-extensions工具，得写成：install-php-extensions -j$(nproc) swoole（它会自动探测并启用）
opcache.enable_cli=0 的位置和 Alpine 下 SSL 支持的显式启用——这两处不手动干预，服务看起来能启，但一发 HTTPS 请求或一开协程就出问题，排查起来极耗时间。 
