Swoole 扩展需手动启用且配置正确才能运行：先确认扩展已安装并启用（php -m | grep swoole），再检查 php.ini 中 extension=swoole 及 hook_flags 配置，协程必须在 Swoole 事件循环中启动。
composer install 时提示 swoole 扩展未启用
装完 swoole 库却跑不起来，八成是 PHP 还没加载扩展。Composer 只管下载代码，不负责启扩展——这是最常被当成“安装失败”的误解点。
- 先运行
php -m | grep swoole，没输出说明扩展根本没装或没启用 - 确认扩展文件存在：
php -i | grep "extension_dir"，再检查该目录下是否有swoole.so（Linux/macOS）或swoole.dll（Windows） - 编辑
php.ini，加一行extension=swoole（注意不是extension=swoole.so，PHP 8.0+ 会自动补后缀） - 如果用的是 Docker 或多版本 PHP（如
php@8.2），务必确认你改的是 CLI 模式实际读取的php.ini，可用php --ini查看路径
composer require swoole/swoole 安装报错：ext-swoole 不存在
这不是库的问题，是 Composer 在校验扩展依赖。默认 swoole/swoole 包声明了 "ext-swoole": "*"，而你本地没启用扩展，它就直接拒绝安装。
- 临时绕过：加
--ignore-platform-reqs参数，比如composer require swoole/swoole --ignore-platform-reqs——但仅限开发环境调试，上线前必须补上扩展 - 更稳妥的做法：先装扩展（用 pecl 或编译），再
composer require，避免后续运行时报Class 'Swoole\Http\Server' not found - 注意版本对齐：PHP 8.2+ 推荐用 Swoole 5.0+；若用 PHP 7.4，别硬上 Swoole 5.x，会因 ZTS/NTS 不匹配直接 core dump
协程环境起不来：Swoole\Coroutine::create() 报错或无反应
装了扩展、require 了包，但协程函数一调就静默退出或抛 Fatal error: Uncaught Swoole\Exception，大概率是没在 Swoole 启动的上下文中运行。
- 协程只能在 Swoole 的事件循环里生效，比如
Swoole\Http\Server回调、Swoole\Coroutine\run()内部，或go(function () { ... })启动的协程中 - 别在普通 CLI 脚本里直接写
Swoole\Coroutine::create(...)—— 没事件循环，协程调度器压根没启动 - 简单验证是否进协程环境：
var_dump(Swoole\Coroutine::getCid() !== -1);，返回false就说明当前不在协程内 - 想快速试协程？写个最小启动脚本：
<?php Swoole\Coroutine\run(function () { go(function () { echo "in coroutine\n"; }); });
配置 enable_coroutine 和 hook_flags 的实际影响
这两个配置决定协程能否“透明”接管传统阻塞调用，比如 file_get_contents、curl_exec。不开钩子，协程里调这些函数照样会阻塞整个进程。
-
enable_coroutine = On是基础开关，但默认只对 Swoole 自家 API 生效（如Swoole\Coroutine\Http\Client） - 要让常见函数也协程化，得配
hook_flags，例如：ini_set('swoole.hook_flags', SWOOLE_HOOK_ALL); - 注意兼容性：开启
SWOOLE_HOOK_CURL后，curl_*系列函数才变成协程安全；但某些老旧扩展（如某些 Redis 扩展）可能与钩子冲突，导致 segfault - 推荐渐进式开启：
SWOOLE_HOOK_STDIO | SWOOLE_HOOK_CURL | SWOOLE_HOOK_FILE，先覆盖最常用场景，再根据日志逐步加
