安装 Swoole 前须核对 PHP 主版本（如 8.1/8.2/8.3），Swoole 5.x 要求 PHP ≥ 8.0，4.8.x 是最后一个支持 PHP 7.4 的稳定版；Linux 推荐用 pecl 安装并确保已装 php-dev 或 php-devel；Windows 需下载匹配 TS/NTS、VC 版本的预编译 DLL 并手动配置 php.ini；安装后需用 php --ri swoole 验证，并显式启用协程 Hook 才能实现异步。
确认 PHP 版本和 Swoole 兼容性
安装 Swoole 前必须核对 php -v 输出的 PHP 主版本（如 8.1、8.2、8.3），Swoole 5.x 要求 PHP ≥ 8.0，Swoole 4.8.x 是最后一个支持 PHP 7.4 的稳定系列。用 php-config --version 查实际编译版本，避免因系统多 PHP 环境导致扩展装错位置。
- PHP 8.3 + 推荐装
swoole 5.1.x - PHP 7.4 仅能用
swoole 4.8.13及以下 -
php --ri swoole在安装后验证是否加载成功，而非只看php -m | grep swoole
Linux 下用 pecl 安装最稳妥
pecl 自动适配当前 phpize 和 php-config 路径，比手动编译出错率低。前提是已安装 php-dev（Ubuntu/Debian）或 php-devel（CentOS/RHEL）包。
sudo apt install php-dev # Ubuntu/Debian sudo yum install php-devel # CentOS 7 sudo dnf install php-devel # CentOS 8+/AlmaLinux
然后执行：
pecl install swoole # 安装过程中会提示是否启用某些特性，回车默认即可（如 async-redis、openssl 支持） # 成功后自动写入 extension=swoole.so 到 /etc/php/*/cli/conf.d/20-swoole.ini
若报错 ERROR: failed to mkdir /tmp/pear/install，说明临时目录权限不足，加 -d temp_dir=/var/tmp 指定路径。
立即学习“PHP免费学习笔记（深入）”；
Windows 下只能用预编译 DLL（无源码编译）
PHP for Windows 不提供 phpize 工具，也不能用 pecl 编译，必须下载对应版本的 .dll 文件。去 https://www.php.cn/link/948d25d346008436180931cd87fb5cf1 找匹配项：
- PHP 线程安全（TS）还是非线程安全（NTS）？查
phpinfo()中Thread Safety行 - VC 版本：PHP 8.2 VC17、PHP 8.1 VC16 —— 必须一致，否则
PHP Startup: Unable to load dynamic library 'swoole' - 扩展文件名形如
php_swoole-5.1.1-8.2-ts-vs17-x64.dll，重命名为php_swoole.dll放入ext/目录 - 在
php.ini加一行：extension=php_swoole.dll
验证异步能力是否真正生效
装完只是第一步，Swoole 默认不开启协程 Hook，file_get_contents、cURL 等仍是同步阻塞。要真正获得异步效果，需显式启用：
// 必须在代码最开始调用（早于任何 IO 操作） Runtime::enableCoroutine(true);// 后续所有支持的函数（包括 PDO、Redis、stream_socket_client）都会自动协程化 go(function () { $content = file_get_contents('https://www.php.cn/link/ef246753a70fce661e16668898810624'); echo strlen($content) . "\n"; }); Swoole\Event::wait();
常见漏点：
- 没调用
Runtime::enableCoroutine()，以为装了扩展就自动异步 - 在
php.ini里写了swoole.enable_coroutine=On，但该配置只影响 CLI 模式，且需 Swoole ≥ 4.5.0 - 用了
curl_init()却没换Swoole\Coroutine\Http\Client，原生 cURL 不受 Hook 影响
真正的异步框架支持，不是“装上就行”，而是从启动方式（php server.php）、协程调度、IO 驱动全链路配合——Swoole 本身是底层引擎，Laravel Octane、Hyperf、Egg.js（PHP 版）这些才是构建在其上的异步应用层，别混淆扩展和框架职责。
