如何在Alpine Linux上安装Swoole扩展

在 Alpine Linux 上通过 pecl 直接安装 Swoole，十有八九会卡在某个编译阶段。原因不复杂——Alpine 默认环境太精简了，连基本的构建工具链都没有准备到位。缺了头文件、少了构建工具，pecl install swoole 基本跑不通，报错信息里经常看到 linux/aio_abi.h: No such file or directory 或者 autoconf: not found 这类提示。

所以，动手之前得先把环境配齐。

先把 Alpine 的构建依赖装好

Alpine 的极简哲学在这里成了绊脚石。gcc、make、autoconf 这些基础组件默认都不带，更别提 OpenSSL 和 Linux 内核头文件了。漏掉其中任何一个，phpize 或 pecl install 都会在中途中断。下面这几个包缺一不可：

• apk add --no-cache autoconf g++ make —— 这组是基础构建链，编译器、链接器都靠它。
• apk add --no-cache openssl-dev —— 少了它，编译时 --enable-openssl 会报错，或者装上的 Swoole 直接缺失 HTTPS 功能。
• apk add --no-cache linux-headers —— 这个最容易被忽略，却是解决 linux/aio_abi.h 找不到的关键。
• apk add --no-cache pcre2-dev —— Alpine 3.14 之后默认用 pcre2 替代了旧版 pcre，所以得装这个新版本。

这几样装好，编译环境基本就到位了。

用 pecl 安装，记得加参数

环境准备好之后，pecl install swoole 能跑通了，但默认安装出来的 Swoole 是不带 OpenSSL 和 HTTP/2 支持的。生产环境下，这两个功能几乎是标配，直接在安装时就得带上。具体操作是这样的：

• 先清掉缓存，避免旧参数干扰：pecl clear-cache
• 显式传参：pecl install swoole --configureoptions '--enable-openssl --enable-http2'
• 安装完成后立即启用：如果是在 Docker 环境里，用 docker-php-ext-enable swoole；如果在普通环境，手动往 php.ini 里加一行 extension=swoole.so。

不过，Alpine 上的 pecl 有时会忽略 --configureoptions。如果安装过程中，编译日志里没有出现 checking for OpenSSL support... yes 这类字样，那就要果断换源码编译的方式。

源码编译更可控，但细节得盯住

直接从 GitHub 拉最新稳定版进行编译，比走 PECL 更可靠——尤其在 Alpine 这种对 PHP 版本比较敏感的环境里。步骤不算多，但每一步都有容易踩的坑：

• 克隆代码并进入目录：git clone https://github.com/swoole/swoole-src && cd swoole-src
• 确认 PHP 版本与 Swoole 版本兼容。比如 PHP 8.2 和 Swoole 4.8.x 就不匹配，装上去会报错。
• 编译的经典三步走：phpize && ./configure --with-php-config=$(which php-config) --enable-openssl --enable-http2，然后 make && make install。

几个常见的问题：

• which php-config 必须有输出，否则 ./configure 会直接报错，找不到 PHP 的编译配置。
• make install 完成后，输出的 swoole.so 路径未必在默认的 extension_dir 里。需要用 php -i | grep extension_dir 确认一下实际目录。
• 如果 php -m 看不到 swoole，但 phpinfo() 页面里却有，那就说明 CLI 和 FPM 加载了不同的 php.ini 文件，两个地方都得分别检查。

验证安装，别只看 php -m

php -m | grep swoole 只检查 CLI 模式，但线上服务通常走的是 FPM。所以稳妥的做法是在三个地方都确认一遍：

• CLI 模式：php -m | grep swoole
• FPM 模式：php-fpm -m | grep swoole，或者直接在 phpinfo() 页面里查找。
• 功能级验证：php --ri swoole，输出信息里会明确显示 openssl 和 http2 是否已经启用。

还有一个容易被忽视的细节：Alpine 的 php.ini 配置是碎片化的，分散在 /etc/php*/conf.d/ 下多个文件里。如果 extension=swoole.so 写错了地方，等于没写。最稳妥的做法是用 php --ini 查看加载顺序，然后优先把启用文件放到加载顺序最末尾的那个 conf.d 目录里。