flask-socketio服务端必须用eventlet或gevent启动，禁用flask run；客户端需匹配协议、路径及socket.io版本；广播须明确broadcast=true或to参数；登录态需自定义事件维护sid映射；nginx需配置upgrade/connection头。
Flask-SocketIO 服务端必须用 eventlet 或 gevent 启动
直接用 flask run 启动会静默失败，浏览器连不上 WebSocket，控制台也看不到明显报错。这是因为 Flask-SocketIO 默认依赖异步服务器，而内置的 Werkzeug 开发服务器不支持 WebSocket 协议。
实操建议：
- 安装
eventlet：pip install eventlet（推荐，兼容性好）或gevent - 启动命令必须显式指定：运行
python app.py，且代码里调用socketio.run(app, host='0.0.0.0', port=5000)—— 不要用app.run() - 如果用了
eventlet，需在导入任何其他包前插入：import eventlet; eventlet.monkey_patch() - 若开发时想快速验证，可临时加
debug=True，但生产环境务必关掉，否则可能暴露 socket 连接细节
客户端连接时必须用完整 URL，且协议要匹配
常见错误是前端写 io() 或 io('http://localhost:5000')，结果控制台报 WebSocket connection to 'ws://localhost:5000/socket.io/...' failed。本质是协议不一致或路径未对齐。
实操建议：
- 确保 HTML 中引入的是与后端一致的 Socket.IO 客户端版本，例如后端装的是
Flask-SocketIO==5.3.6，前端就该用https://cdn.socket.io/4.7.2/socket.io.min.js（对应 v4.x） - 连接时显式传入完整地址：
const socket = io('http://localhost:5000');（开发）或io('https://yourdomain.com')（生产） - 如果 Flask 启在非根路径（如
/chat），需前后端同时配置path：服务端设SocketIO(app, path='/chat/socket.io')，客户端写io({ path: '/chat/socket.io' }) - HTTPS 站点下不能用
http://连接，否则浏览器直接拦截，会卡在opening状态
消息广播必须用 emit() 的 broadcast=True 参数
很多人写 socket.emit('message', data)，结果只有自己收到；或者用 socketio.emit() 却没指定 room，导致所有客户端（包括发信者）都收到两遍——这是对作用域理解偏差。
实操建议：
- 发给「除自己外的所有人」：用
socket.emit('msg', data, broadcast=True) - 发给「所有人（含自己）」：用
socketio.emit('msg', data) - 需要房间隔离（如不同聊天室）：先
join_room('general')，再socketio.emit('msg', data, to='general') - 注意：
broadcast=True仅对当前命名空间有效；多个命名空间需分别处理 - 别在事件处理器里混用
socket.emit和socketio.emit，容易漏掉接收方
用户身份和连接状态得靠 sid + 自定义存储来维护
Socket.IO 没内置登录态，request.sid 是每次连接唯一的字符串，但刷新页面就变；request.args 可传用户名，但不安全；session 在 WebSocket 升级后不可用。
实操建议：
- 首次连接时，让前端在
connect后立刻发一次login事件，带 token 或用户名：socket.emit('login', { user: 'alice' }) - 服务端用字典或 Redis 存映射：
clients[request.sid] = username，断开时删掉：@socketio.on('disconnect') def handle_disconnect(): clients.pop(request.sid, None) - 避免用全局 list 存
sid，高并发下可能竞态；小项目可用dict，大流量建议上 Redis - 不要依赖
request.environ.get('HTTP_AUTHORIZATION')做鉴权——WebSocket 握手请求里不一定带这个头，得靠自定义事件传递
Upgrade 和 Connection 头，这点比 HTTP 路由容易漏掉。还有，移动端 Safari 对长连接更敏感，超时时间、重连策略得调得更保守些。Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
