# WebSocket 关闭代码 1009：消息过大

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

## 根因

WebSocket 帧或消息大小超出服务器配置的最大有效负载大小（通常为 64KB 或 1MB），导致连接关闭。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| ws 8.16.0 (Node.js) | active | — | — |
| websockets 12.0 (Python) | active | — | — |
| Tornado 6.4.0 | active | — | — |
| Spring WebSocket 6.1.0 | active | — | — |

## 解决方案

1. ```
   Increase the maximum message size on the server. For Node.js with 'ws': `const wss = new WebSocket.Server({ maxPayload: 1024 * 1024 });`. For Python with 'websockets': `async with websockets.serve(handler, host, port, max_size=2**20):`.
   ```
2. ```
   Compress large messages using a binary format like Protocol Buffers or MessagePack before sending over WebSocket. Example: serialize with `msgpack.pack(data)` and send as binary frame.
   ```
3. ```
   Implement message chunking on the client and reassembly on the server using a custom protocol (e.g., prefix each chunk with sequence number and total count).
   ```

## 无效尝试

- **** — The server may not support fragmentation or may reject partial messages if not properly reassembled. (70% 失败率)
- **** — TCP buffer size is unrelated to application-level WebSocket message limits. (90% 失败率)
- **** — The limit is typically server-configured, not library-specific; switching libraries rarely helps. (60% 失败率)