Flask SocketIO设置async_mode="threading"后无法连接客户端

关键修复步骤 #

• 版本兼容性检查
  Flask-SocketIO依赖的python-socketio、python-engineio版本必须匹配，threading模式要求python-socketio >=5.x、python-engineio >=4.x，同时要和Flask版本适配。执行以下命令升级到兼容版本：

  pip install --upgrade flask-socketio python-socketio python-engineio
  

• 使用正确的服务启动方式
  禁止用Flask原生的app.run()启动服务，必须调用SocketIO的run()方法：

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

  原生app.run()无法正确初始化threading模式下的SocketIO服务，这是连接立即断开的常见原因。

• 客户端连接参数验证
  确保客户端连接的路径、命名空间与服务端一致（默认命名空间为/），同时JS客户端的socket.io.js版本要和服务端python-socketio版本匹配（比如服务端用5.x，客户端对应4.x或5.x版本）。

• 线程触发事件的正确写法
  从线程触发事件时，直接调用sio.emit()即可，但要保证线程在SocketIO服务启动后创建。推荐用sio.start_background_task()创建后台线程，示例：

  import threading
  import time
  
  def background_task():
      while True:
          time.sleep(3)
          sio.emit('thread_event', {'content': '线程推送的消息'})
  
  @sio.on('connect')
  def on_connect():
      print('客户端已连接')
      sio.start_background_task(background_task)
  
  sio = SocketIO(app, async_mode="threading")
  

额外排查方向 #

• 暂时关闭debug模式，部分场景下debug的自动重载机制会干扰threading模式的SocketIO运行。
• 检查端口占用与防火墙设置，确保服务端口（如5000）未被占用，客户端能正常访问该端口。

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