Connection refused 错误主因是 Swoole 服务未启动或端口被占，需加 -d 参数或设 daemonize=1，检查端口占用及进程存在；Docker 中需正确映射端口并 bind 0.0.0.0。
Connection refused 错误：检查 swoole_server 是否已启动且端口未被占用
这个错误最常见，不是代码写错了，而是服务根本没跑起来。Swoole 的 TCP/HTTP 服务器默认不自动后台驻留，运行完脚本就退出，客户端连时自然报 Connection refused。
- 确保启动命令带
-d（daemonize=1）或在代码里设$server->set(['daemonize' => 1]) - 检查端口是否被占用：
lsof -i :9501或netstat -tuln | grep 9501（把9501换成你用的端口） - 启动后用
ps aux | grep php确认进程还在，别只看命令回车了就以为成功了 - 如果用 Docker，确认宿主机端口映射正确，且容器内
bind地址不是127.0.0.1（应改用0.0.0.0）
Client timeout / Connection reset by peer：关注 set 中的超时与心跳配置
这类问题往往出现在长连接场景，比如 WebSocket 或自定义 TCP 协议。客户端等不到响应、主动断开，或服务端突然 kill 掉空闲连接。
-
tcp_keepalive默认关闭，公网或 NAT 环境下容易被中间设备断连，建议开启：['tcp_keepalive' => 1] -
heartbeat_check_interval和heartbeat_idle_time必须配对使用；例如设为60和180，表示每 60 秒扫一次，连续 180 秒没收到 ping 就踢掉连接 -
open_tcp_nodelay设为1可减少小包延迟，但会略微增加 CPU 开销，高频小包交互（如游戏帧同步）建议开 - 注意：WebSocket 的
onMessage里阻塞太久（比如同步 curl、sleep），也会触发客户端超时，得拆成协程调用
SSL 连接失败（handshake failed）：证书路径、协议版本与 Swoole 版本强相关
swoole_http_server 或 swoole_websocket_server 开启 HTTPS 时，稍有不慎就卡在 TLS 握手阶段。
Swoole 6.1.1
下载
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
- 证书路径必须是绝对路径，相对路径在 daemon 模式下会失效，写成
/var/www/cert/fullchain.pem，别用./cert/... - Swoole v4.8.0+ 才完整支持 TLS 1.3，老版本客户端（如某些 iOS WebView）连不上，可临时降级到
tls_version => 'TLSv1.2' - 私钥如果带密码，Swoole 不支持，必须先用
openssl rsa -in key.pem -out key-decrypted.pem解密 - Nginx 做反向代理时，别在 Swoole 层再套 SSL，否则双重加密 + 重复证书校验，大概率握手失败
协程客户端连不上本地 Swoole 服务：注意 127.0.0.1 vs localhost 的 DNS 解析差异
用 Swoole\Coroutine\Http\Client 或 Co\Socket 连本机服务时，localhost 有时比 127.0.0.1 慢甚至失败。
- Linux 下
localhost可能走 IPv6（::1），而 Swoole server 只 bind 了 IPv4，导致连不上；强制用127.0.0.1更稳 - 在
/etc/hosts里注释掉::1 localhost行，能快速验证是不是这个原因 - Docker 容器内访问宿主机服务，别用
127.0.0.1（那是容器自己），改用host.docker.internal（Mac/Win）或宿主机真实 IP（Linux）
Swoole 的连接问题，八成不在协议逻辑里，而在启动状态、网络路径、配置粒度这些“边缘”位置。特别是 daemonize、证书路径、IPv4/6、Docker 网络这几处，改一行就能从连不上变成通了。
