WebSocket 帧超过最大大小：接收 1048576 字节，最大允许 65536 字节（错误代码 1009）
WebSocket frame exceeds maximum size: received 1048576 bytes, max allowed 65536 bytes (Error code 1009)
ID: communication/websocket-1009-message-too-big
版本兼容性
| 版本 | 状态 | 引入 | 弃用 | 备注 |
|---|---|---|---|---|
| RFC 6455 | active | — | — | — |
| Node.js ws library 8.12.0 | active | — | — | — |
| Python websockets 12.0 | active | — | — | — |
| Go gorilla/websocket 1.5.0 | active | — | — | — |
根因分析
WebSocket 服务器或客户端以代码 1009 关闭连接，因为接收的消息负载超过配置的最大帧大小，通常是由于未分割的大负载或配置错误的限制。
English
WebSocket server or client closes connection with code 1009 because the received message payload exceeds the configured maximum frame size, typically due to unsplit large payloads or misconfigured limits.
官方文档
https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/statusCode解决方案
-
Implement message splitting on the sender: break large payloads (e.g., > 64KB) into multiple WebSocket messages with a sequence identifier, then reassemble on the receiver. This avoids exceeding the frame limit.
-
Increase the server's max frame size (e.g., in Python websockets: set 'max_size' parameter to None or a larger value like 10MB).
-
Use compression (e.g., permessage-deflate extension) to reduce payload size below the limit, if both client and server support it.
无效尝试
常见但无效的做法:
-
60% 失败
Increasing the max frame size on the client only shifts the problem; the server may still enforce a smaller limit, causing asymmetric failures.
-
75% 失败
Disabling fragmentation entirely (e.g., setting 'permessage-deflate' off) doesn't reduce payload size and may not be supported by all libraries.
-
70% 失败
Switching to a different WebSocket library without adjusting limits often results in the same default cap (e.g., 65536 bytes in many implementations).