Swoole服务端启动失败？如何排查故障及解决方法？

本文共计837个文字，预计阅读时间需要4分钟。

说明：

实操建议：

• 先运行 php -m | grep swoole，没输出就说明 CLI 环境根本没加载扩展
• 查 CLI 的配置文件位置：php --ini，重点关注 Loaded Configuration File 路径（比如 /etc/php/8.2/cli/php.ini）
• 确认 swoole.so 文件存在，再往对应 php.ini 里加一行：extension=swoole.so（不要写绝对路径，除非必要）
• 如果用了多版本 PHP（如 8.1/8.2 并存），注意 CLI 和 FPM 的 php.ini 是分开的，别改错文件

启动时提示 Address already in use

说明：端口被占是高频原因，尤其阿里云、腾讯云服务器上，可能已有 Nginx、另一个 Swoole 实例、甚至残留的僵尸进程在监听 9501 或你指定的端口。

实操建议：

• 查端口占用：sudo lsof -i :9501 或 netstat -tulnp | grep :9501
• 杀掉残留进程：kill -9 $(lsof -t -i :9501)（谨慎使用，确认是自己的进程）
• 换端口测试最省事：$http = new swoole_http_server("0.0.0.0", 9502);，排除冲突
• 注意：阿里云/腾讯云的安全组必须放行该端口——光关系统防火墙不够，安全组才是第一道门

浏览器访问一直 pending，无响应

说明：代码跑起来了、进程也起来了，但请求卡在 pending，常见于新版 Swoole（v5+）未指定运行模式，或监听地址写死公网 IP。

实操建议：

• 强制指定 SWOOLE_BASE 模式启动（尤其 v5.0+）：$server = new swoole_http_server("0.0.0.0", 9501, SWOOLE_BASE);
• 监听地址别写成服务器公网 IP（如 "119.123.45.67"），Linux 下应写 "0.0.0.0" 或内网 IP（ifconfig 查）
• 检查是否误启用了 HTTPS 配置但没配证书，导致握手失败静默卡住
• 用 telnet 127.0.0.1 9501 直连测试，能通说明服务正常，问题出在网络链路或客户端

Permission denied 绑定端口失败

说明：Linux 下绑定 1024 以下端口（如 80、443）需要 root 权限，普通用户直接 php start.php 必然失败。

实操建议：

• 开发阶段直接换高位端口：9501、8080、8888 —— 别硬刚权限问题
• 生产环境若真需 80，要么用 sudo php start.php（不推荐），要么用 nginx 反代（更安全、标准）
• 检查是否误在 php.ini 中禁用了 stream_socket_server：disable_functions 里删掉它

最容易被忽略的一点：Swoole 不走 Apache/Nginx，它是独立进程；你以为改了 nginx 配置就能访问，其实完全无关。服务没起来，或者起了但没暴露到外网，这两个层面得分开验证。