Flask 3.0 不支持 WebSocket,需借助 Flask-SocketIO 或 websockets 库;前者依赖 gevent/eventlet 并适配 Werkzeug 3.x,后者轻量但需自行管理连接与状态;生产部署须配置 Nginx 和异步服务器,不可用 WSGI。

Flask 3.0 本身不支持 WebSocket
直接用 flask 启动 WebSocket 服务会失败——它没有内置 WebSocket 协议处理能力,也没有 socketio 或 websockets 的集成层。你写的 @app.route('/ws') 路由根本不会被识别为 WebSocket 端点,浏览器发起 new WebSocket('ws://...') 时只会收到 404 或 405 错误。
必须引入第三方库补足这一能力,主流选择是 Flask-SocketIO 或原生 websockets 库。前者兼容性好、API 熟悉;后者更轻量、无依赖,但需自行管理连接生命周期和路由分发。
用 Flask-SocketIO 实现最简可用的长连接
Flask-SocketIO 依赖底层异步服务器(如 eventlet 或 gevent),Flask 3.0 默认用 Werkzeug 3.x,而 Werkzeug >= 3.0 已移除对 eventlet 的 monkey patch 支持,所以必须显式降级或换用 gevent。
- 安装时指定兼容组合:
pip install flask-socketio==5.3.6 gevent==23.9.1(Flask-SocketIO 5.3.6+已适配 Werkzeug 3.x) - 启动时禁用 Werkzeug 开发服务器:
socketio.run(app, host='0.0.0.0', port=5000, server_options={'gevent': True}) - 前端连接地址不是
/ws,而是ws://localhost:5000/socket.io/(协议由 Socket.IO 自动协商) - 后端事件监听用
@socketio.on('connect'),不是@app.route
示例服务端片段:
立即学习“Python免费学习笔记(深入)”;
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
from flask import Flask
from flask_socketio import SocketIO
<p>app = Flask(<strong>name</strong>)
socketio = SocketIO(app, cors_allowed_origins="*")</p><p>@socketio.on('connect')
def handle_connect():
print('Client connected')</p><p>@socketio.on('message')
def handle_message(data):
socketio.send(f'Echo: {data}')</p><p>if <strong>name</strong> == '<strong>main</strong>':
socketio.run(app, host='0.0.0.0', port=5000, server_options={'gevent': True})
用 websockets 库绕过 Flask 路由系统
如果你只需要纯 WebSocket(不要 Socket.IO 的自动重连、房间、广播等),websockets 是更干净的选择。但它和 Flask 不共享请求上下文,request、session、g 全部不可用,认证和状态管理得自己做。
- 不能和
flask.run()共存——要另起一个异步服务器,比如asyncio.run(websockets.serve(...)) - URL 路径需在
websocketshandler 中手动解析,例如判断path == '/ws/chat' - 若需与 Flask 共享数据(如用户登录态),得用外部存储(Redis、内存字典加锁)同步
- 客户端仍用标准
WebSocketAPI,无需引入socket.io-client
最小化 handler 示例:
import asyncio import websockets <p>connected_clients = set()</p><p>async def websocket_handler(websocket, path): connected_clients.add(websocket) try: async for message in websocket: await asyncio.wait([client.send(message) for client in connected_clients]) finally: connected_clients.remove(websocket)</p><h1>单独运行:asyncio.run(websockets.serve(websocket_handler, "localhost", 8765))</h1><p>
生产环境部署的关键限制
无论选哪种方案,Flask 3.0 + WebSocket 在生产中都不能只靠 socketio.run() 或 websockets.serve()。WSGI 服务器(如 Gunicorn)根本不理解 WebSocket 协议,Nginx 默认也会在 60 秒后关闭空闲连接。
- Nginx 需显式开启 WebSocket 支持:
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade" - Gunicorn 不支持 WebSocket,必须换用
gevent或eventletworker(如gunicorn -k gevent -w 1 app:app) - 若用
websockets,得用uvicorn或自建asyncio服务,无法接入 WSGI 生态 - Flask 3.0 的
app.app_context()在 WebSocket 回调中无效,所有数据库操作建议用线程安全的异步驱动(如asyncpg)或加锁访问同步 ORM
真正麻烦的从来不是“怎么连上”,而是“连上之后怎么安全地读写共享状态、怎么优雅下线、怎么横向扩展”。这些细节不提前想清楚,上线后就只能靠日志里反复出现的 RuntimeError: Event loop is closed 和 ConnectionResetError 来提醒你。

















