编译Swoole需先安装PHP开发包（如Ubuntu用sudo apt install php-dev，CentOS用sudo yum install php-devel），确保php-config在PATH中；链接错误加LDFLAGS="-lpthread"；扩展不加载检查php.ini和swoole.so路径；协程环境下须改用Swoole协程API替代curl_*等同步函数。
configure 时提示找不到 php-config
编译 Swoole 前必须让 configure 找到 PHP 的开发头文件和配置工具，否则直接报错退出。常见现象是：configure: error: Cannot find php-config 或 php.h: No such file or directory。
本质是没装 PHP 开发包，或者装了但 php-config 不在 $PATH 中。
- Ubuntu/Debian 系统：运行
sudo apt install php-dev（注意不是php-cli） - CentOS/RHEL：运行
sudo yum install php-devel（或dnf install php-devel） - 如果用了多版本 PHP（如通过
phpbrew或asdf），确保当前 shell 激活的是目标版本，并检查which php-config是否输出路径；若无输出，用完整路径指定：./configure --with-php-config=/path/to/php-config
make 编译报错 undefined reference to `pthread_*`
这是典型的链接阶段缺失线程库，尤其在较新 GCC 或 Alpine Linux 上高频出现。错误信息里常含 undefined reference to `pthread_create` 或类似。
原因不是代码写错了，而是 Swoole 的 Makefile 没自动加上 -lpthread，或系统默认不链接 libpthread。
- 临时解决：在
make前加环境变量：export LDFLAGS="-lpthread"，再执行make - 更稳妥做法：修改
Makefile，找到EXTRA_LDFLAGS行，在其后追加-lpthread - Alpine 用户注意：必须同时装
musl-dev和gcc，仅build-base不够，缺头文件也会触发同类报错
php --ri swoole 显示 extension not loaded
编译成功、make install 也完成了，但 PHP 就是不认这个扩展——大概率是 extension=swoole.so 没生效，或加载路径不对。
别急着重装，先确认三件事：
- 查
php --ini输出的配置文件路径，编辑对应php.ini，添加extension=swoole.so（不是绝对路径） - 确认
swoole.so实际位置：通常在/usr/lib/php/*/swoole.so或/usr/local/lib/php/extensions/*/swoole.so；用find /usr -name 'swoole.so' 2>/dev/null快速定位 - 如果 PHP 是多 SAPI（比如 CLI + FPM），注意它们可能读不同
php.ini；php -m和php-fpm -m结果可能不一致
启用协程后 curl 或 MySQLi 调用失败
源码安装的 Swoole 默认开启协程支持，但老项目里直接用 curl_exec 或 mysqli_query 会卡住甚至崩溃，这不是 bug，是协程 IO 未接管导致的阻塞穿透。
核心矛盾：原生函数不兼容协程调度，必须换用 Swoole 提供的协程版 API。
- HTTP 请求改用
Swoole\Coroutine\Http\Client，别碰curl_*函数 - MySQL 改用
Swoole\Coroutine\Mysql，别用mysqli_*或PDO（除非显式关闭协程 Hook） - 如果必须保留同步调用，启动前调用
Swoole\Runtime::enableCoroutine(false)关闭协程 Hook，但会失去大部分性能优势
最容易被忽略的是：即使只跑 CLI 脚本，只要用了 Swoole\Coroutine\run()，就已进入协程环境，所有 IO 默认被 Hook —— 这时候还混用同步函数，结果就是“看起来没报错，但程序不动了”。
