AWS WebSocket API Gateway与浏览器端TypeScript应用连接异常求助

一、先排查网关的关键设置 #

• 检查阶段的空闲超时与保活配置：AWS API Gateway的WebSocket阶段有独立的Idle Timeout设置，和$connect路由的超时不是一回事。建议开启Managed WebSocket Ping，设置30-60秒的间隔，让网关主动发送ping帧维持连接，避免无数据时被断开。
• 验证CORS与Origin权限：浏览器WebSocket会携带Origin头，确认API Gateway的资源策略或阶段设置里，已经允许你的前端域名访问。如果Origin被拦截，可能直接触发1006断开且无日志提示。
• 确认$connect集成的响应格式：$connect对应的Lambda（或其他集成）必须返回200 OK，且响应头的Sec-WebSocket-Protocol要和请求头完全一致。如果响应格式错误，网关会静默断开连接。
• 开启全量日志排查：在CloudWatch的API Gateway日志组里开启Full Request/Response Logging，查看连接建立后的完整请求响应细节，很多时候1006的原因藏在这里，比如网关层面的权限校验失败、集成响应异常。

二、保活机制是必须的 #

浏览器原生WebSocket没有内置心跳逻辑，而wscat/ws这类工具默认会发送ping帧维持连接，这就是为什么工具能正常连接但浏览器不行的核心原因之一。

两种实现方式：

• 客户端主动发心跳：每30秒左右发送一个空消息或特定ping指令，触发网关回复pong。
• 网关主动发ping：利用AWS的Managed WebSocket Ping功能，网关定时发ping，浏览器原生WebSocket会自动回复pong，无需额外代码。

三、客户端替代方案 #

• ws库（浏览器兼容版）：ws库的浏览器打包版本自带自动重连、心跳机制，比原生WebSocket更稳定，直接引入或通过构建工具打包即可使用。
• Socket.IO：封装了WebSocket的高级功能，自带自动重连、心跳、协议降级（WebSocket不可用时自动用轮询），适合前端场景。注意要在API Gateway配置对应路由处理Socket.IO的消息帧。
• 自定义封装原生WebSocket：自己实现心跳和重连逻辑，示例代码：

const wsUrl = 'wss://your-api-gateway-endpoint';
let ws;
let pingTimer;

function initWebSocket() {
  ws = new WebSocket(wsUrl, ['your-auth-protocol']);
  
  ws.onopen = () => {
    console.log('连接建立');
    // 每30秒发送心跳
    pingTimer = setInterval(() => {
      if (ws.readyState === WebSocket.OPEN) {
        ws.send(JSON.stringify({ type: 'ping' }));
      }
    }, 30000);
  };

  ws.onclose = () => {
    clearInterval(pingTimer);
    // 指数退避重连，避免频繁请求
    setTimeout(initWebSocket, 5000);
  };

  ws.onerror = (err) => {
    console.error('连接错误:', err);
    ws.close();
  };
}

initWebSocket();

四、其他需要检查的点 #

• 浏览器环境限制：确保前端页面是HTTPS（或localhost），浏览器不允许在HTTP页面使用wss协议，否则会直接断开。
• 认证会话有效性：虽然认证通过，但确认$connect返回的connectionId是否有效，以及后续消息发送的权限是否正常，部分情况下认证通过但后续权限不足也会触发断开。

内容的提问来源于stack exchange，提问作者Shaun Yates