PHP安装swoole扩展

• Swoole官网

安装准备

安装前必须保证系统已经安装了下列软件

• 4.8 版本需要 PHP-7.2 或更高版本
• 5.0 版本需要 PHP-8.0 或更高版本
• 6.0 版本需要 PHP-8.1 或更高版本
• gcc-4.8 或更高版本
• make
• autoconf

安装Swool扩展

• 安装官方文档
• 安装后需要再php.ini中增加扩展配置

extension="swoole.so"

推荐启用的 PHP 配置

在 php.ini 中添加或修改以下配置以优化 Swoole：

; 错误显示（开发环境建议启用）
display_errors = On
display_startup_errors = On
error_reporting = E_ALL

; 内存和时间限制（根据需求调整）
memory_limit = 1G       ; Swoole 常驻内存，建议调高
max_execution_time = 0  ; 脚本不超时（由 Swoole 控制）

; 禁用函数安全限制（Swoole 需要）
disable_functions = ""  ; 确保不禁用 exec、shell_exec 等（如需进程管理）

; 启用 OPcache（提升性能）
opcache.enable = 1
opcache.enable_cli = 1  ; CLI 模式下也启用

编译选项

这里是./configure 编译配置的额外参数，用于开启某些特性

编译安装配置

./configure \
    --enable-openssl=yes \
    --enable-sockets=yes \      # 建议启用
    --enable-mysqlnd=yes \     # 建议启用
    --enable-curl=yes \        # 建议启用
    --enable-cares=yes \       # 建议启用
    --enable-brotli=yes \
    --enable-zstd=no \
    --enable-pgsql=no \
    --enable-odbc=no \
    --enable-oracle=no \
    --enable-sqlite=no \
    --enable-thread=no \
    --enable-ioring=no

安装依赖命令

# Ubuntu/Debian
sudo apt-get install -y \
    libssl-dev \
    libcurl4-openssl-dev \
    libc-ares-dev \
    libbrotli-dev \
    libpq-dev  # 如需 PostgreSQL

# CentOS/RHEL
sudo yum install -y \
    openssl-devel \
    libcurl-devel \
    c-ares-devel \
    brotli-devel \
    postgresql-devel  # 如需 PostgreSQL

配置选项速查表

配置选项	默认值	作用说明	推荐建议	依赖库
enable sockets support	no	启用 PHP 原生 sockets 协程化支持（底层 TCP/UDP 开发）	✅ 选 no：仅用高级协议（HTTP/WebSocket） ❌ 选 yes：需自定义协议	-
enable openssl support	no	启用 SSL/TLS 加密（HTTPS/WSS 必备）	✅ 必选 yes	libssl-dev 或 openssl-devel
enable mysqlnd support	no	启用 MySQL 协程客户端（高性能非阻塞操作）	✅ 选 no：无 MySQL 需求 ❌ 推荐 yes：高并发 MySQL 场景	mysqlnd
enable curl support	no	启用协程 cURL（替代原生阻塞式 curl）	✅ 选 no：无需高性能 HTTP 客户端 ❌ 推荐 yes：爬虫/微服务调用	libcurl-dev
enable cares support	no	启用异步 DNS 解析（避免阻塞协程）	✅ 选 no：直接使用 IP ❌ 推荐 yes：高并发 HTTP 客户端	libc-ares-dev
enable brotli support	yes	启用 Brotli 压缩（比 Gzip 更高压缩率）	✅ 推荐保持 yes	libbrotli-dev
enable zstd support	no	启用 Zstandard 压缩（速度优于 Brotli）	✅ 选 no：Brotli 已足够 ❌ 选 yes：需极致压缩性能	libzstd-dev
enable PostgreSQL support	no	启用 PostgreSQL 协程客户端	✅ 保持 no：除非明确需要	libpq-dev
enable ODBC support	no	启用 ODBC 协程客户端（SQL Server/Oracle 等）	✅ 保持 no	unixodbc-dev
enable Oracle support	no	启用 Oracle 协程客户端（需 OCI8）	✅ 保持 no	Oracle Instant Client
enable Sqlite support	no	启用 SQLite 协程客户端	✅ 保持 no	sqlite3-dev
enable thread support	no	启用多线程模式（需 PHP ZTS 版本）	✅ 保持 no：协程模式足够	-
enable iouring support	no	启用 Linux io_uring 异步 I/O（需内核 ≥5.1）	✅ 选 no：非高版本内核 ❌ 选 yes：需极致文件性能	liburing-dev

Swoole 编译附加选项说明

配置选项说明

配置选项	默认值	作用说明	适用场景	依赖/注意事项
–enable-http2	no	启用 HTTP/2 协议支持	需高性能 HTTP/2 服务（如 gRPC）	需 OpenSSL ≥1.0.2
–enable-swoole-json	no	启用 Swoole 内置 JSON 编解码优化	高频 JSON 操作场景（替代 json_encode/json_decode）	需 PHP ≥7.2
–enable-swoole-pgsql	no	启用 PostgreSQL 协程客户端（旧版配置，推荐用 --enable-pgsql）	同 --enable-pgsql	需 libpq-dev
–enable-debug-log	no	启用调试日志（记录更详细的运行时信息）	开发环境问题排查	影响性能，生产环境禁用
–enable-trace-log	no	启用追踪日志（记录协程切换等底层事件）	深度性能调优或 Swoole 内部机制研究	日志量极大，仅调试使用
–enable-swoole-hook	all	启用系统调用钩子（将阻塞函数转为协程式）	需协程化原生函数（如 sleep/file_get_contents）	可能引发兼容性问题，需测试
–enable-swoole-global-hook	no	全局启用协程钩子（覆盖所有 PHP 代码）	全项目无侵入式协程化	风险高，谨慎使用
–with-jemalloc	no	链接 jemalloc 内存分配器（替代 glibc 的 malloc）	高并发场景减少内存碎片	需安装 jemalloc 开发库
–with-libpq-dir	-	指定 PostgreSQL 库路径（非标准安装时使用）	自定义 PostgreSQL 安装路径	示例：–with-libpq-dir=/opt/pgsql
–with-openssl-dir	-	指定 OpenSSL 库路径（非标准安装时使用）	自定义 OpenSSL 安装路径	示例：–with-openssl-dir=/opt/openssl

功能模块选项

配置选项	默认值	作用说明	依赖项
–enable-swoole-redis	yes	启用 Redis 协程客户端（需单独安装 swoole_redis 扩展）	-
–enable-swoole-sqlite	no	启用 SQLite 协程客户端	sqlite3-dev
–enable-swoole-curl	no	启用协程 cURL 客户端（替代原生 curl）	libcurl-dev
–enable-swoole-zip	no	启用 Zip 压缩解压协程支持	libzip-dev

编译安装

下载 swoole 源码

https://github.com/swoole/swoole-src/releases
https://pecl.php.net/package/swoole
https://gitee.com/swoole/swoole/tags

从源码编译安装

下载源代码包后，在终端进入源码目录，执行下面的命令进行编译和安装

ubuntu 没有安装 phpize 可执行命令：sudo apt-get install php-dev 来安装 phpize

快速安装（官方示例）

cd swoole-src && \
phpize && \
./configure && \
sudo make && sudo make install

进阶完整编译（官方示例）

以下脚本会下载并编译 master 分支的源码，需保证你已安装所有依赖，否则会遇到各种依赖错误。

mkdir -p ~/build && \
cd ~/build && \
rm -rf ./swoole-src && \
curl -o ./tmp/swoole.tar.gz https://github.com/swoole/swoole-src/archive/master.tar.gz -L && \
tar zxvf ./tmp/swoole.tar.gz && \
mv swoole-src* swoole-src && \
cd swoole-src && \
phpize && \
./configure \
--enable-openssl --enable-sockets --enable-mysqlnd --enable-swoole-curl --enable-cares --enable-swoole-pgsql && \
sudo make && sudo make install

PECL安装（推荐，根据提示安装简单）

Swoole 项目已收录到 PHP 官方扩展库，除了手动下载编译外，还可以通过 PHP 官方提供的 pecl 命令，一键下载安装

使用系统默认php版本安装

pecl install swoole

指定php版本安装（如果存在多个php版本）

# 进入指定的php版本/bin目录中
/usr/local/php8.2/bin/php install swoole

官方文档的安装方式

通过 PECL 安装 Swoole 时，在安装过程中它会询问是否要启用某些功能，这也可以在运行安装之前提供，例如：

pecl install -D 'enable-sockets="no" enable-openssl="yes" enable-http2="yes" enable-mysqlnd="yes" enable-swoole-json="no" enable-swoole-curl="yes" enable-cares="yes"' swoole

#或者
pecl install --configureoptions 'enable-sockets="no" enable-openssl="yes" enable-http2="yes" enable-mysqlnd="yes" enable-swoole-json="no" enable-swoole-curl="yes" enable-cares="yes"' swoole

验证安装：

编译完成后执行 php --ri swoole 检查已启用功能。

php --ri swoole