常见现象是php --ri swoole能显示版本但扩展不生效，根本原因是swoole.so与PHP ABI不兼容；需确认PHP版本、清理残留、指定正确php-config重装，并注意pecl安装时版本匹配及Docker环境差异。
php --ri swoole 显示版本但扩展不生效
常见现象是运行 php --ri swoole 能看到输出，但 php -m 里没有 swoole，或者写个 new Swoole\Http\Server 直接报类不存在。根本原因不是没装，而是 PHP 加载的 swoole.so 和当前 PHP 版本 ABI 不兼容——比如用 PHP 8.2 编译的扩展，硬塞进 PHP 8.1 的环境里。
实操建议：
- 先确认 PHP 主版本和编译器 ABI：运行
php -v看主版本（如8.1.27），再跑php-config --version和php-config --extension-dir，确保后续编译时用的是同一套php-config - 卸载所有残留：删掉
ext/swoole源码目录、/usr/lib/php/*/swoole.so（或pecl install写死的路径）、php.ini里所有extension=swoole行 - 重装必须指定 PHP 配置路径：
phpize && ./configure --with-php-config=/usr/bin/php-config && make && sudo make install；注意/usr/bin/php-config得是你当前php -v对应的那个
pecl install swoole 安装后版本错乱
pecl install swoole 默认装最新稳定版，但新版可能不支持旧 PHP（比如 swoole 5.0+ 已放弃 PHP 7.4 支持），而旧版又可能缺你想要的 API（如 Swoole\Coroutine\WaitGroup 在 4.8.0+ 才完整）。这不是“装错了”，是没锁版本。
实操建议：
- 查清楚你要的 PHP 版本能用的最高 swoole 版本：访问 Swoole 官方环境要求页，对照你的
php -v输出找兼容表 - 用 pecl 指定安装：比如 PHP 8.0 应该用
pecl install swoole-4.11.5，而不是pecl install swoole - 装完立刻验证：运行
php -r "echo SWOOLE_VERSION;"，结果必须和你pecl install时指定的版本一致；若不一致，说明系统里有多个swoole.so，优先加载了旧的
docker 中 swoole 扩展始终加载失败
Docker 常见错误是基础镜像 PHP 版本和你本地开发机不一致，或者用了 php:alpine 却没装 g++ 和 linux-headers，导致编译失败后静默跳过，最后 php -m 里压根没 swoole。
实操建议：
- 别用
pecl install在 Alpine 上编译：Alpine 的 musl libc 和 glibc 不兼容，优先用apk add php81-swoole（对应你的 PHP 版本包名） - 在 Debian/Ubuntu 镜像中，确保构建阶段安装了
php-dev和zlib1g-dev（swoole 依赖 zlib） - 检查
docker build日志末尾有没有Installing '/usr/lib/php/*/swoole.so'这行；没有就代表没装上，别信中间的 “Build complete” - 运行容器后，进 shell 执行
ls -l $(php-config --extension-dir)/swoole.so，文件存在才说明真装上了
启用 openssl 或 http2 后 swoole 启动报错
加了 --enable-openssl 或 --enable-http2 参数编译 swoole，但启动服务时提示 undefined symbol: SSL_CTX_set_alpn_select_cb 或直接段错误，本质是 OpenSSL 版本太低（
实操建议：
- 先查系统 OpenSSL 版本：
openssl version -a，如果显示OpenSSL 1.1.0或更老，必须升级到1.1.1或3.x - 编译时显式指定路径：
./configure --with-php-config=/usr/bin/php-config --with-openssl-dir=/usr/local/ssl（路径得和你新装的 OpenSSL 一致） - 如果用的是 Ubuntu 20.04+ 或 CentOS 8+，系统自带 OpenSSL 1.1.1，但 PHP 可能链接了旧的
libssl.so.1.0.0，此时要删掉旧库或用LD_LIBRARY_PATH强制指向新版
