WebSocket close code怎么配置或排查

我第一次认真处理 WebSocket 断线时，日志里只有一个 1006，直觉是“服务端返回了 1006”。后来发现判断反了：1006 是没有收到 Close frame 时的异常观测结果，不能作为浏览器 close() 的发送参数。配置 close code 的关键，是把协议标准码、应用自定义码和保留观测码分开，再把 code、reason、wasClean 一起记录。

前端主动关闭时，浏览器只能传 1000 或 3000–4999 的码；1005、1006、1015 只用于表达“没有状态码、异常断开、TLS 握手失败”等观测结果，不能硬编码发送。排查时先看关闭握手是否完成，再决定是否重连。

WebSocket close code先分成三组

标准码适合描述协议层事实。常用的 1000 是正常关闭，1001 表示端点离开，1002 是协议错误，1003 是不支持的数据类型，1007 是载荷数据不符合消息类型，1008 是策略违规，1009 是消息过大，1011 是服务端遇到未预期情况。服务重启和暂时过载还可以分别使用 1012、1013。

3000–3999 通常留给库、框架或注册过的应用码，4000–4999 适合项目内部约定。例如鉴权过期可以约定 4001，但不要把“网络断开”也伪装成业务码。1005、1006、1015 是保留值：前者表示未收到状态码，1006 表示异常断开，1015 表示 TLS 握手失败。它们可以出现在事件里，却不应写入主动关闭代码。

我会先固定项目自己的关闭约定

真正上线后，最麻烦的不是记不住 1009，而是不同服务各自发一套“看起来合理”的数字。我更愿意把码集中定义，再让关闭函数只接受这些定义。这样前端日志、网关指标和服务端日志可以用同一组关键词对齐。

const CLOSE_CODE = {
  NORMAL: 1000,
  AUTH_EXPIRED: 4001, // 业务码只在团队约定的私有范围内使用
  SERVER_BUSY: 1013,  // 暂时过载，交给重连策略决定是否稍后再试
};

function closeSocket(ws, code, reason) {
  // 连接未打开时不要重复发送 Close frame，避免把状态机弄乱
  if (ws.readyState !== WebSocket.OPEN) return;

  // reason 按 UTF-8 计字节，不按 JavaScript 字符数量估算
  const bytes = new TextEncoder().encode(reason).length;
  if (bytes > 123) throw new Error('close reason 超过 123 个 UTF-8 字节');

  // 业务码和标准码由调用方传入，保留码不要放进这个配置表
  ws.close(code, reason);
}

这里有一个容易踩到的边界：浏览器 API 的主动关闭参数不是“任意 1000–4999”。指定时只能是 1000 或 3000–4999，传入 1002、1011 这类标准异常码会触发参数异常；这些码更常由服务端根据协议或处理结果发送。reason 也按 UTF-8 字节计算，中文很容易比肉眼看到的字符数更快达到上限。

close 事件里四个字段要一起看

只打印 event.code，定位信息通常不够。我会至少保留下面四项，并给每次重连附上一个连接编号。code 说明收到的关闭状态，reason 给出对端愿意公开的短原因，wasClean 反映关闭是否按握手完成，readyState 则确认当前对象是否已经进入 CLOSED。

socket.addEventListener('close', (event) => {
  // 只记录诊断字段，不把 1006 当成可以发送的业务码
  const report = {
    code: event.code,
    reason: event.reason,
    wasClean: event.wasClean,
    readyState: socket.readyState,
  };

  console.info('websocket closed', report);

  // 异常断开才考虑重连，正常关闭通常由业务动作触发
  if (!event.wasClean && [1006, 1012, 1013].includes(event.code)) {
    scheduleReconnect({ jitterMs: 500, maxDelayMs: 30000 });
  }
});

1006 出现时，先查浏览器网络面板、代理超时、TLS 和服务端进程日志；它只告诉你没有拿到 Close frame，不会单独告诉你根因。1002、1007、1009 更像协议或消息边界线索；1011 则应回到服务端异常日志。至于 wasClean=false，它是重要信号，但也不能代替服务端日志。

规模上来后，重连策略比换数字更重要

低流量环境里，断线后立刻 new WebSocket() 似乎没问题；连接数上来后，代理重启、服务发布或临时过载会让大量客户端同时重连。我通常对 1006、1012、1013 做随机初始延迟，再做有上限的指数退避；对 1008 或明确的 4001 鉴权失效，则先刷新凭据或让用户重新登录，避免无意义重试。

我的判断顺序是：先确认是不是主动关闭，再确认有没有 Close frame，然后按 code 找协议/服务端方向，最后才调整重连。这样不会把 TLS、代理空闲超时或消息过大都归因于“close code 配错”。

常见问题

1006 能不能在 socket.close(1006) 里使用？

不能。它是没有收到 Close frame 时的保留观测码，应在日志和监控里解释为异常断开。

自定义业务码应该选哪一段？

项目内部通常选 4000–4999 并维护一张码表；跨团队或需要注册的应用可评估 3000–3999。

reason 写得越详细越好吗？

不是。reason 只适合放短、人类可读且不含敏感信息的原因，并确保 UTF-8 编码不超过 123 字节，详细上下文应写入带连接编号的服务端日志。