PHP连接WebSocket需依赖第三方库，日志关键在打点位置、内容精简与防丢失；textalk/websocket可通过继承拦截send/receive并捕获异常；异步场景须用线程安全日志并带连接ID；握手失败优先查HTTP状态码、Sec-WebSocket-Accept及SSL配置。

PHP 本身不原生支持 WebS

ocket 客户端长连接（fsockopen 或 stream_socket_client 可连，但无法处理 WebSocket 协议握手和帧解析），所以「PHP 连接 WebSocket」几乎总是依赖第三方库（如 textalk/websocket、ratchet/pawl 或 reactphp/socket + 自定义协议层）。日志记录的关键不在“怎么写 log”，而在于「在哪打点、打什么、怎么避免日志爆炸或丢失」。

用 textalk/websocket 时如何注入日志逻辑

这是最轻量、最常用的同步 WebSocket 客户端库。它不内置日志，但所有关键动作都可通过继承或包装 WebSocket 类来拦截：

• 重写 send() 方法，在调用父类前记录发送内容（注意截断大消息，避免日志撑爆磁盘）
• 在 receive() 返回前记录原始响应帧（含 opcode、payload length），这对排查粘包/截断问题极有用
• 捕获 WebSocketException，并记录 $e->getMessage() 和 $e->getTraceAsString() 的前 200 字符（全 trace 太长，且含敏感上下文）

示例：在 send 前加日志

use WebSocket\Client;

class LoggedClient extends Client {
    private $logger;

    public function __construct($url, array $options = [], $logger = null) {
        parent::__construct($url, $options);
        $this->logger = $logger ?: error_log(...);
    }

    public function send($message) {
        $this->logger("WS SEND: " . (strlen($message) > 100 ? substr($message, 0, 100).'...' : $message));
        return parent::send($message);
    }
}

用 reactphp + clue/reactphp-buzz 做异步连接时的日志陷阱

异步场景下，日志顺序和上下文极易错乱。常见错误是直接在 on('data') 回调里调用 file_put_contents —— 多个并发连接会互相覆盖或阻塞主线程。

• 必须用线程安全的日志方式：error_log()（底层是系统 syslog 或 stderr）或 Monolog 配合 StreamHandler 并启用 useLocking
• 每个连接需带唯一 ID（比如用 spl_object_hash($connection)），否则无法区分哪条 log 属于哪个 socket
• 不要在 on('error') 中记录完整 Exception 对象 —— React 的错误常含循环引用，var_export 会卡死

关键参数：确保 StreamHandler 初始化时传 ['locking' => true]，否则高并发下日志行会错位或丢失。

WebSocket 握手失败时，该查哪几行日志

90% 的连接失败不是代码问题，而是握手阶段被拦截。重点检查以下位置的日志输出：

• HTTP status code：非 101 Switching Protocols 就说明没升级成功（可能是 Nginx 没配 proxy_http_version 1.1 和 Upgrade 头）
• Sec-WebSocket-Accept 值是否与客户端计算一致（可用在线工具校验，不一致说明服务端签名算法被篡改或中间件修改了响应体）
• SSL 层日志：若用 wss://，要确认 PHP 的 stream_context 是否设置了 'ssl' => ['verify_peer' => false]（开发可关，生产必须开且配对 CA）

一个典型错误信息：WebSocket connection to 'wss://xxx' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED —— 这说明 TCP 层就失败了，此时 PHP 日志里根本不会出现任何 WebSocket 相关记录，得去查服务器端口监听状态（netstat -tuln | grep :443）和防火墙规则。

真正难的不是记日志，而是让每条日志能回答一个问题：是网络问题？协议问题？还是业务数据触发了服务端主动断连？把 Connection-ID、Timestamp、Opcode、HTTP Status 这四样固定打在每条 log 开头，比堆砌 trace 有用得多。