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

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

## 根因

WebSocket 帧或消息负载超过服务器或中间代理配置的最大允许大小，许多实现中默认为 1 MB。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Node.js ws 8.14 | active | — | — |
| Python websockets 12.0 | active | — | — |
| Nginx 1.24 | active | — | — |
| AWS ALB | active | — | — |
| Go gorilla/websocket 1.5 | active | — | — |

## 解决方案

1. ```
   在服务器端增加最大消息大小，例如在 Node.js ws 中：`const wss = new WebSocket.Server({ maxPayload: 10 * 1024 * 1024 });` 允许 10 MB 负载。
   ```
2. ```
   将大消息拆分为多个小帧并在接收端重组，例如发送每个 512 KB 的块并附带序列号。
   ```
3. ```
   配置 Nginx 允许更大的 WebSocket 帧：添加 `proxy_read_timeout 300s; proxy_send_timeout 300s;`，如果位于反向代理后，确保增加 `client_max_body_size`。
   ```

## 无效尝试

- **Ignore the close frame and force reconnect immediately** — The underlying message size issue persists; reconnection will trigger the same error. (85% 失败率)
- **Compress the entire message payload using gzip but send as a single frame** — If the compressed payload still exceeds the limit, the error persists; also, compression may not be supported by all WebSocket libraries. (60% 失败率)
- **Increase the WebSocket frame size limit on the client side only** — The server or proxy enforces the limit; client-side change alone does not resolve the issue. (90% 失败率)