使用PyInstaller打包Flask-SocketIO应用时遇Invalid async_mode错误求助

问题根源 #

• PyInstaller打包时无法自动识别Flask-SocketIO依赖的异步驱动（eventlet/gevent），导致运行时找不到有效async_mode
• 手动导入gevent但未正确配置异步环境，且使用阻塞式sleep()破坏SocketIO事件循环，引发实时更新失效

解决方案步骤 #

1. 明确指定异步模式并配置环境

修改app.py，显式指定异步驱动并初始化猴子补丁（必须执行，确保异步机制生效）：

from time import sleep
from datetime import datetime
from flask import Flask, render_template
from flask_socketio import SocketIO, emit
import eventlet

# 猴子补丁：替换标准库阻塞方法为异步实现
eventlet.monkey_patch()

app = Flask(__name__)
# 显式指定async_mode，避免打包后自动检测失败
socketio = SocketIO(app, async_mode='eventlet')

# 后续路由、事件处理函数保持不变

先安装依赖：

pip install eventlet flask-socketio pyinstaller

2. 配置PyInstaller打包规则

如果使用app.spec文件，补充hiddenimports和静态资源路径：

a = Analysis(
    ['app.py'],
    pathex=[],
    binaries=[],
    # 打包templates和static目录，保持路径结构
    datas=[('templates', 'templates'), ('static', 'static')],
    # 添加所有eventlet相关隐式依赖
    hiddenimports=['eventlet', 'eventlet.hubs', 'eventlet.hubs.epolls', 'eventlet.hubs.selects', 'engineio.async_drivers.eventlet'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=[],
    noarchive=False,
)
pyz = PYZ(a.pure)
exe = EXE(
    pyz,
    a.scripts,
    a.binaries,
    a.datas,
    [],
    name='app',
    debug=False,
    bootloader_ignore_signals=False,
    strip=False,
    upx=True,
    upx_exclude=[],
    runtime_tmpdir=None,
    console=True  # 保持控制台输出，方便调试
)

如果直接用命令打包，执行：

pyinstaller --hidden-import eventlet --hidden-import eventlet.hubs --hidden-import eventlet.hubs.epolls --hidden-import eventlet.hubs.selects --hidden-import engineio.async_drivers.eventlet --add-data "templates;templates" --add-data "static;static" app.py

3. 替换阻塞sleep为异步方法

原代码中的sleep(1)会阻塞SocketIO事件循环，导致消息无法实时推送，替换为SocketIO提供的异步睡眠：

@socketio.on('start_streaming')
def start_streaming(data):
    selected_msg_type = data.get('msg_type')
    print(f"Selected Message Type: {selected_msg_type}")
    
    ls = [f'File{i}.txt' for i in range(1, 11)]
    max_num = len(ls)
    for i in range(0, max_num):
        emit('new_data', {'value': f'[{datetime.now().strftime("%Y-%m-%d %H:%M:%S")}] - {ls[i]}: Done', 'progress': int(((i+1)/max_num)*100)})
        socketio.sleep(1)  # 异步睡眠，不阻塞事件循环
    
    results = f"Total cases: {len(ls)}"
    emit('show_results', results)

4. 优化启动代码（可选）

打包后关闭debug模式，避免引发异常：

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

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