Flask-SocketIO 必须用 socketio.run() 启动并安装 eventlet/gevent，否则退化为轮询；需正确初始化实例、配置 CORS、前后端版本/命名空间/事件名严格一致，广播需用 broadcast=True 或指定 room。
Flask-SocketIO 初始化失败，socketio.run() 报错或不生效
直接用 flask run 启动 Flask-SocketIO 应用会静默失效——因为 Socket.IO 依赖长连接和异步事件循环，而默认的 Werkzeug 开发服务器不支持 WebSocket 协议。
必须改用 socketio.run() 替代 app.run()，且需确保已安装兼容的异步服务器（如 eventlet 或 gevent）：
- 优先装
eventlet：pip install eventlet；它对 WebSocket 兼容性最好，且无需额外配置 - 如果已装
gevent，启动时得显式指定：socketio.run(app, server_options={'gevent': True}) - 没装任一异步库时，
socketio.run()会退化为轮询（polling），页面看不到实时效果，但控制台无报错——这是最隐蔽的坑
前端连接不上 /socket.io/，浏览器报 404 或跨域错误
Socket.IO 客户端默认尝试访问同源的 /socket.io/ 路径，但 Flask-SocketIO 默认不暴露该路径——除非你正确初始化了 SocketIO 实例并挂载到 Flask app 上。
常见漏点：
立即学习“Python免费学习笔记（深入）”；
-
SocketIO实例没传入app，或传的是未配置静态路由的 app（比如用了工厂模式但忘了在 create_app 里 init） - 前端脚本加载的是 CDN 版
socket.io-client（如https://cdn.socket.io/4.7.2/socket.io.min.js），但后端用的是较新版本（如 5.x），协议不兼容导致握手失败 - 开发时前端跑在
http://localhost:3000，后端是http://localhost:5000，没配 CORS：必须初始化时加cors_allowed_origins="*"（生产环境请换具体域名）
@socketio.on('message') 不触发，事件监听完全失灵
事件名大小写、命名空间、客户端 emit 方式三者必须严格一致。Flask-SocketIO 默认在全局命名空间 "/" 工作，但很多前端示例会显式指定 namespace="/chat"，而后端没同步声明，就收不到。
检查要点：
- 服务端监听用的是
@socketio.on('my_event', namespace='/chat')，那前端 connect 时就得写io('http://localhost:5000/chat') - 客户端 emit 的事件名必须和
@socketio.on()第一个参数完全相同，包括单双引号、空格、下划线——socket.emit('user login')和@socketio.on('user_login')是两个事件 - 如果用了自定义命名空间，
connect事件也得单独监听：@socketio.on('connect', namespace='/chat')，否则连上都不通知
消息能发不能收，或广播（socketio.emit()）只发给自己
socketio.emit() 默认作用域是当前命名空间下的所有客户端（包括 sender 自己），但新手常误以为它是“群发”，结果发现只有自己收到——其实是因为没断开重连，旧连接还挂着，新连接又没触发 join。
典型场景与对策：
- 需要排除 sender：用
broadcast=True参数，例如socketio.emit('msg', data, broadcast=True) - 想发给特定房间：先
join_room('room-123')，再socketio.emit('msg', data, room='room-123')；注意room是字符串，不是列表 - 使用
session['sid']或request.sid做用户绑定时，别在 request 上下文外读取request.sid——它只在连接、接收事件时有效
真实项目里，连接管理比发消息难得多。很多人卡在“用户刷新页面后房间状态丢失”，这得靠服务端存储 + join/leave 显式管理，而不是依赖内存变量。
