如何在API Gateway的$connect等路由中自定义修改WebSocket状态码

算力阿峰

2026-9-27

自定义WebSocket关闭状态码方案说明

问题原因排查

你当前的代码不生效是正常的，disconnect路由对应的Lambda是WebSocket连接完成关闭流程后的回调通知函数，它的返回值仅用于告知API Gateway回调任务的执行状态，和WebSocket协议层面的关闭状态码完全无关，因此无法通过修改它的返回值来修改返回给客户端的关闭码。

不同场景下的实现方案

场景1：服务端主动触发连接关闭

这种情况可以直接调用API Gateway提供的连接管理接口DeleteConnection，主动指定自定义的4000-4999区间状态码和关闭原因，Node.js示例代码如下：

const AWS = require('aws-sdk');
exports.handler = async (event) => {
  // 初始化API Gateway管理客户端
  const apigwManagement = new AWS.ApiGatewayManagementApi({
    apiVersion: '2018-11-29',
    endpoint: `${event.requestContext.domainName}/${event.requestContext.stage}`
  });
  // 调用关闭接口，指定自定义状态码和原因
  await apigwManagement.deleteConnection({
    ConnectionId: event.requestContext.connectionId,
    StatusCode: 4090,
    Reason: "业务逻辑触发连接关闭"
  }).promise();
  return { statusCode: 200 };
};

通过这种方式返回的关闭状态，客户端可以正常获取到event.code=4090和对应的event.reason内容。

场景2：客户端主动触发连接关闭

如果是客户端主动调用socket.close()发起关闭，此时WebSocket关闭握手已经在API Gateway层完成，无法通过后端Lambda修改返回的状态码，可以选择两种替代方案：

客户端主动调用关闭方法时直接携带自定义状态码和原因，示例：socket.close(4090, "客户端主动关闭")，此时客户端可以直接获取到对应参数
客户端在关闭前先发送一条自定义业务关闭消息，携带状态码参数，服务端收到消息后调用上述DeleteConnection接口主动发起关闭，即可将自定义状态码返回给客户端