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