Flask-SocketIO 必须使用 eventlet 或 gevent 异步模式，否则降级为长轮询导致假连接；需显式指定 async_mode、正确配置 CORS 和静态资源路径、emit 时注意 broadcast/namespace/room 参数；生产环境需调优并发与心跳参数，并用 Redis 实现多进程消息共享。
Flask-SocketIO 初始化必须用 eventlet 或 gevent，否则 connect 就失败
默认 Flask 开发服务器不支持 WebSocket 协议，Flask-SocketIO 启动时若没指定异步模式，会退化成长轮询（HTTP polling），connect 事件可能触发但实际连接是假的，前端反复重连、socket.connected 始终为 false。
- 安装时必须显式选一个异步服务器：
pip install eventlet（推荐）或pip install gevent - 初始化时要传
async_mode：socketio = SocketIO(app, async_mode='eventlet')，不能依赖自动探测 - 启动命令也要匹配：
eventlet下直接python app.py；如果用了gevent，得用gevent.wsgi.WSGIServer包一层，否则照样 fallback - Windows 上
eventlet有时会卡在monkey_patch()，加一句import eventlet; eventlet.monkey_patch()到入口文件最顶上
emit() 发送数据前必须确认 namespace 和 room 正确
emit() 默认只发给当前客户端（room=request.sid），不是全局广播。很多实时通知场景下误以为“发了就所有人收到”，结果只有自己看见。
- 想发给所有人：显式写
broadcast=True，例如socketio.emit('msg', data, broadcast=True) - 跨 namespace 通信要带
namespace参数：socketio.emit('alert', data, namespace='/admin')，否则默认在/ - 发到特定 room 要先
join_room()，且 room 名不能含斜杠或空格；room是字符串，不是列表，别传[room_id] - 服务端
emit()不受客户端连接状态检查，如果用户已断开，消息直接丢弃，不会报错也不会重试
客户端连接不上？检查 static 文件路径和 CORS 配置
前端加载 socket.io.js 失败、io(...) 报 404 或跨域拒绝，是最常见的“连不上”原因，和后端逻辑无关。
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
- 不要手动下载
socket.io.js放本地 —— Flask-SocketIO 自带静态路由，前端直接用https://cdn.socket.io/4.7.2/socket.io.min.js或/socket.io/socket.io.js（后者需确保 Flask 的static_url_path没被改乱） - 开发时前后端端口不同（如 Flask 在 5000，Vue 在 3000），必须配
cors_allowed_origins：SocketIO(app, cors_allowed_origins="http://localhost:3000")，设成*在生产环境会被浏览器拒绝 - 客户端连接 URL 必须带完整协议和端口：
io("http://localhost:5000", { path: "/socket.io/" })，漏掉http://或端口会导致降级为 polling 甚至连接超时
生产部署时 eventlet 并发数不够，连接数上不去
本地跑几十个连接没问题，一上服务器并发几百就卡住、新连接 hang 住，大概率是 eventlet 默认的 green thread 数量限制或文件描述符没调够。
- 启动时加
workers=4和worker_class="eventlet"（用 Gunicorn）；单独用eventlet时，代码里加import eventlet; eventlet.sleep(0)防止主线程阻塞 - Linux 下检查
ulimit -n，至少设到 8192；Docker 容器要加--ulimit nofile=65536:65536 -
SocketIO实例不能放函数里反复创建，必须全局单例；多个进程间无法共享 socket 连接，要用 Redis 作 message queue：SocketIO(app, message_queue='redis://') - 心跳超时参数容易被忽略：
ping_timeout=60和ping_interval=25建议显式设，否则 Nginx 默认 60s 断连，前端会频繁触发reconnect_attempt
WebSocket 不是“开了就能实时”，从 client 端的连接管理、server 端的异步模型选择，到反向代理层的超时配置，任何一环松动都会让双向通信变成单向等待。真正难的不是写 emit() 和 on()，而是把这一整条链路里的隐性约束都对齐。
