# WebSocket 关闭帧收到状态码 1009（消息过大）

- **ID:** `communication/websocket-close-frame-1009-message-too-large`
- **领域:** communication
- **类别:** protocol_error
- **错误码:** `1009`
- **验证级别:** ai_generated
- **修复率:** 82%

## 根因

WebSocket 消息负载超出服务器或代理允许的最大帧大小（默认 65535 字节）。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| ws 8.16.0 | active | — | — |
| nginx 1.24.0 | active | — | — |
| AWS ALB 2.0 | active | — | — |

## 解决方案

1. ```
   Fragment the large message into smaller chunks on the client and reassemble on the server: In JavaScript, split payload into 32KB chunks and send each with a sequence number; on the server (Node.js), buffer chunks until all received.
   ```
2. ```
   Increase the server's max frame size: In nginx, set `proxy_read_timeout 300s;` and `proxy_buffers 8 32k;` but more importantly configure `proxy_http_version 1.1;` and ensure the WebSocket library (e.g., ws in Node.js) sets `maxPayload: 256 * 1024`.
   ```
3. ```
   Use a message queue (e.g., Redis Pub/Sub) to offload large payloads and send only references via WebSocket.
   ```

## 无效尝试

- **Increase the WebSocket frame size limit on the client side only** — The limit is enforced by the server or intermediate proxy; client changes alone don't override it. (85% 失败率)
- **Compress the payload with gzip before sending** — WebSocket frames are already binary-safe; compression must be negotiated via extensions (permessage-deflate) at connection setup. (75% 失败率)
- **Switch to long-polling with HTTP POST to avoid frame limits** — Long-polling introduces latency and doesn't solve the underlying payload size issue; the same data may still hit HTTP body limits. (65% 失败率)