WebSocket close 事件怎样区分主动与异常断开

WebSocket 的 close 事件不能独立证明“用户主动退出”或“网络故障”。可靠的做法是同时记录本地应用是否请求关闭，以及 CloseEvent 的 code、reason、wasClean：前者表达业务意图，后者表达浏览器观察到的关闭结果。

1000 不等于用户点了退出，wasClean 为 true 也不等于由客户端发起。只有应用自己保存的关闭意图，才能说明自己的代码曾主动请求结束这条连接。

WebSocket API 规范地址：https://websockets.spec.whatwg.org/。我的处理取舍是让断开记录保留两条独立线索，不强行合成“主动就是正常、被动就是异常”。以下是原创客户端设计示例，没有连接真实服务器，也没有运行结果记录。

先记录关闭事件能证明的事实

考虑一个任务进度页面：用户离开面板时会关闭连接，服务端维护时也可能结束会话，网络中断则可能使关闭握手无法完成。这些情况都可能触发 close，不能只用一个布尔变量给所有断开归因。

1000 表示正常关闭状态；1006 表示异常关闭的保留状态，不能作为关闭帧里的状态码发送。看到1006时应保留“异常关闭、根因未知”的结论，而不是直接写成断网。浏览器刻意不向脚本提供足以区分所有连接失败原因的细节。

为每条连接单独保存主动关闭意图

下面的函数为一个 WebSocket 实例创建一个闭包。每次建立新连接都调用一次，避免旧连接的停止标记污染新连接。调用方传入自己部署的地址和记录函数，示例没有内置演示服务器。

function createTrackedSocket(url, onClosed) {
  const socket = new WebSocket(url);
  // 状态只属于当前实例，重建连接时重新初始化
  let localIntent = null;
  let sawError = false;

  socket.addEventListener("error", () => {
    // 记录异常信号，不在这里推断 TLS、DNS 或网络根因
    sawError = true;
  });

  socket.addEventListener("close", (event) => {
    const protocolOutcome =
      event.code === 1006 || !event.wasClean
        ? "abnormal"
        : "clean";

    onClosed({
      localIntent,
      protocolOutcome,
      code: event.code,
      wasClean: event.wasClean,
      sawError,
      // 不把服务端原始原因直接送进日志或页面
      hasReason: event.reason.length > 0
    });
  }, { once: true });

  return {
    socket,
    stop() {
      // 已在关闭或已关闭时，不声称本次调用发起了握手
      if (socket.readyState === WebSocket.CLOSING ||
          socket.readyState === WebSocket.CLOSED) {
        return false;
      }

      localIntent = "panel-disposed";
      try {
        // 固定短原因与合法状态码，避免任意文本超过字节限制
        socket.close(1000, "panel disposed");
        return true;
      } catch (error) {
        // 调用失败则撤销本次意图记录，交给调用方处理错误
        localIntent = null;
        throw error;
      }
    }
  };
}

stop 返回 true 的含义只是本地关闭请求已执行，不等于连接已经干净结束。连接还在 CONNECTING 时调用 close 也可能导致异常结束，因此“有本地停止意图”和“异常关闭”可以同时成立。即便记录了本地意图，远端也可能恰好同时开始关闭；这个标记不证明网络上的绝对发起顺序。

所有主动停止入口都应经过这个封装。如果其他代码直接调用暴露的 socket.close，localIntent 就不会记录那次动作。较大的项目可以进一步隐藏原始实例，只暴露发送和停止等受控方法。

集中生成断开记录而不猜测根因

我的日志分类会先保留协议结果，再附带业务意图。例如 localIntent 存在且 protocolOutcome 是 abnormal，表示页面确实想停，但协议结果仍是异常。没有本地意图且结果 clean，只能说明这段代码没有记录主动请求，不能自动标成“服务端故障”。

// 由业务接入记录函数，输出受控字段
function reportClose(record) {
  console.info("socket-close", {
    localIntent: record.localIntent,
    protocolOutcome: record.protocolOutcome,
    code: record.code,
    wasClean: record.wasClean,
    sawError: record.sawError,
    hasReason: record.hasReason
  });
}
// 实际项目调用 createTrackedSocket(实际地址, reportClose)
// 面板销毁时调用返回对象的 stop()，不另外重复注册关闭逻辑

浏览器的 reason 字段可作为补充线索，但它由对端协议行为影响，可能为空。若确实要展示原因，应以普通文本呈现；业务判断使用双方约定的状态码或应用消息，不能依靠人类可读字符串中的几个关键词。示例只记录是否存在原因文本，避免将自由文本误当成稳定协议字段。

把恢复策略与关闭事实分开

close 事件说明旧连接已经结束，是否恢复是另一项业务决策。面板已经销毁时应停止恢复；登录状态失效时应先处理身份；根因未知的异常断开可以进入有次数上限、带退避的恢复策略。本文不加入自动重连定时器，避免把“如何分类断开”扩展成另一套连接管理器。

不要在 error 和 close 两个监听里分别重连，否则同一次失败可能产生两个新连接。可以在 error 中收集信号，在 close 中统一交给连接管理层决策。若页面已有定时器、订阅或心跳资源，显式停止时也要由管理层清理，防止销毁后的回调继续创建连接。

需要自定义业务关闭码时，浏览器 close 方法显式传入的状态码仅允许1000或3000到4999；原因按 UTF-8 计算不得超过123字节。4001等数值没有“必然是登录失效”的通用含义，必须由自己的客户端与服务端共同约定。

用场景清单整理交接与常见疑问

交接时至少写清本地停止入口、连接标识、受控关闭字段和恢复决策负责人。不要只留一条“WebSocket挂了”的消息，也不要把空 reason 补写成未经证实的故障原因。

code 是1000就不用关注了吗？

还要看业务是否预期结束。服务端正常结束长期订阅，对业务而言也可能需要重新订阅；状态码不替代业务生命周期。

有本地主动关闭意图，wasClean 为什么仍可能是 false？

意图不是结果。关闭期间发生异常，或连接尚未建立时停止，都可能让二者同时出现。

只有 close 事件能区分断网与服务器重启吗？

不能可靠区分。需要结合连接标识、时间和服务端或代理日志；浏览器没有提供一个通用的根因枚举。

事实依据：WHATWG WebSockets 标准、RFC6455 关闭状态码、MDN close 方法参数说明。