使用Eventlet的Flask-SocketIO：客户端协议版本不兼容错误排查

问题描述 #

尝试用Flask-SocketIO搭配Eventlet搭建WebSocket连接时，持续报错：客户端使用的Socket.IO或Engine.IO协议版本不受支持。已确认服务端与客户端使用兼容版本，但问题仍未解决。

服务端配置 #

已安装依赖版本 #

pip install flask-socketio==5.3.2
pip install python-socketio==5.3.0
pip install python-engineio==4.3.1
pip install eventlet

服务端代码（app.py） #

from flask import Flask, render_template
from flask_socketio import SocketIO, send, emit
import eventlet

# 使用eventlet处理异步I/O
eventlet.monkey_patch()

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your_secret_key'
socketio = SocketIO(app, async_mode='eventlet', cors_allowed_origins='*')

@app.route('/')
def index():
    return render_template('index.html')

@socketio.on('message')
def handle_message(msg):
    print('Message received: ' + msg)
    send('Message received: ' + msg)

@socketio.on('custom_event')
def handle_custom_event(json):
    print('Received json: ' + str(json))
    emit('response', {'data': 'Custom event response'})

# cPanel的WSGI入口
def application(environ, start_response):
    return socketio.server.handle_request(environ, start_response)

if __name__ == '__main__':
    socketio.run(app, host='0.0.0.0', port=5000, debug=True)

客户端配置 #

客户端代码（templates/index.html） #

<!DOCTYPE html>
<html>
<head>
    <title>Flask-SocketIO with Eventlet</title>
    <!-- 使用兼容版本的Socket.IO -->
    <script src="https://cdn.socket.io/4.3.2/socket.io.min.js"></script>
    <script type="text/javascript">
        document.addEventListener('DOMContentLoaded', (event) => {
            var socket = io();

            socket.on('connect', function() {
                socket.send('User has connected!');
            });

            socket.on('message', function(data) {
                console.log('Message from server: ' + data);
            });

            socket.on('response', function(data) {
                console.log('Custom event response: ' + data.data);
            });

            function sendMessage() {
                socket.send('Hello from client!');
            }

            function sendCustomEvent() {
                socket.emit('custom_event', {data: 'Client sent custom event'});
            }

            window.sendMessage = sendMessage;
            window.sendCustomEvent = sendCustomEvent;
        });
    </script>
</head>
<body>
    <h1>Flask-SocketIO with Eventlet</h1>
    <button onclick="sendMessage()">Send Message</button>
    <button onclick="sendCustomEvent()">Send Custom Event</button>
</body>
</html>

问题截图 #

解决方案 #

1. 调整依赖版本匹配
   当前python-engineio==4.3.1与python-socketio==5.3.0存在协议细节兼容问题，升级python-engineio到稳定兼容版本：

   pip install python-engineio==4.4.1
   

   （python-socketio 5.3.0要求python-engineio >=4.3.0,<5.0.0，4.4.1是该区间内的稳定版本，可修复协议匹配问题）

2. 指定Eventlet稳定版本
   避免新版Eventlet与旧版Flask-SocketIO适配问题，重新安装指定版本：

   pip uninstall -y eventlet
   pip install eventlet==0.33.3
   

3. 优化客户端连接配置
   客户端初始化Socket时，显式指定传输方式并确认路径，减少协议协商错误：

   var socket = io('/', {
       transports: ['websocket', 'polling']
   });
   

4. 开启调试日志排查
   启动服务时添加日志参数，查看协议协商细节：

   socketio.run(app, host='0.0.0.0', port=5000, debug=True, logger=True, engineio_logger=True)
   

   通过日志可确认客户端发送的协议版本与服务端支持版本是否一致，进一步定位问题。

内容的提问来源于stack exchange，提问作者user23470475