如何使用Python Flask和SocketIO轻量级构建WebSocket简易聊天室并推送消息？

本文共计1199个文字，预计阅读时间需要5分钟。

Flask 框架本身不支持 WebSocket，因此需要借助第三方库来实现 WebSocket 功能。一种常见的方法是使用 Flask-SocketIO。以下是一个简单的示例，展示如何使用 Flask-SocketIO 来处理 WebSocket 连接：

真正轻量又靠谱的路径只有一条：用 Flask-SocketIO —— 它不是“纯 WebSocket”，但会自动降级到长轮询（polling），兼容老旧环境；同时保留了 Flask 的路由风格和 session、g 等上下文能力。

• Flask-SocketIO 底层依赖 python-socketio 和异步服务器（eventlet 或 gevent），不装对应并发库会启动失败，报错类似 RuntimeError: You need to use the eventlet server
• 开发阶段用 eventlet 最省事：pip install flask-socketio eventlet，然后启动时加 async_mode="eventlet"
• 别用 threading 模式做生产部署，它无法处理真正的并发连接，只是模拟，撑不过 10 个用户

怎么让 SocketIO 和 Flask 共享 session / 用户状态

很多人卡在这儿：前端发来消息，后端想查当前登录用户的 user_id，结果 session 是空的，或者每次连接都是新 session。

根本原因是：WebSocket 连接建立时不会自动携带 Cookie（尤其跨域时），而 Flask-SocketIO 默认不启用 session 同步。必须手动配置并显式读取。

立即学习“Python免费学习笔记（深入）”；

• 服务端初始化要传 manage_session=True：SocketIO(app, manage_session=True, async_mode="eventlet")
• 前端连接时得带上凭证：如果用 io()，需加 { withCredentials: true }；如果是跨域，后端还得配 cors_allowed_origins
• session 在 @socketio.on("connect") 里不可靠，建议改用 @socketio.on("auth") 手动传 token，再解码存到 flask.g 或自定义连接映射字典里
• 别依赖 request.sid 做用户绑定——它是连接 ID，不是用户 ID；一个用户开两个标签页，会有两个 sid

广播消息到大厅所有人，但别发回给自己

实现“大厅聊天室”最常写的逻辑就是：用户 A 发一条消息，除 A 外所有人收到。但新手常误用 emit(..., broadcast=True)，结果自己也收到了，造成消息重复渲染。

关键在 include_self=False 这个参数，默认是 True，文档里藏得深，不注意就踩坑。

• 正确写法：socketio.emit("message", {"text": txt}, broadcast=True, include_self=False)
• 如果只想发给某房间（比如 "lobby"），用 room="lobby" + include_self=False，别混用 namespace 和 room 逻辑
• 房间名不要带斜杠或点号，socketio.join_room("user.123") 可能触发内部解析异常；用下划线或连字符更稳："user_123"
• 广播性能没问题，Flask-SocketIO 内部做了连接遍历优化；但别在循环里反复 emit，应合并数据一次性推

部署时 nginx 报 400 或连接立即断开

这是线上最典型的故障：开发机一切正常，一上 nginx 就连不上，控制台显示 WebSocket connection to 'wss://...' failed，日志里 nginx 记着 400 Bad Request。

根本原因就两个：HTTP 协议升级头没透传、SSL 配置不匹配。

• nginx 配置里必须显式透传 Upgrade 和 Connection 头：
  

  proxy_set_header Upgrade $http_upgrade;<br>proxy_set_header Connection "upgrade";

• 如果用 HTTPS，确保 wss:// 前端连接地址和 nginx 的 server_name 一致，且证书有效；自签名证书会导致浏览器直接拒连
• location /socket.io 的路径必须和 Flask 初始化时的 path 参数一致（默认是 /socket.io），否则握手 404
• 别在 nginx 里加 proxy_buffering off 之类乱七八糟的优化，Flask-SocketIO 自己会处理流控

复杂点在于：同一个域名下既要跑普通 HTTP 接口，又要跑 SocketIO，路径隔离和 header 透传必须精确对齐，差一个字母或少一行配置，连接就静默失败。这时候看 nginx error log 比看 Flask 日志还管用。