Pyinstaller 打包程序后出现：ValueError: Invalid async_mode specified，开发环境没问题

正常打包后运行 exe，终端会报错：

sh 复制代码

Exception in thread Thread-1:
Traceback (most recent call last):
  File "threading.py", line 932, in _bootstrap_inner
  File "threading.py", line 870, in run
  File "main.py", line 9, in run_server
  File "server\app.py", line 19, in create_app
  File "flask_socketio\__init__.py", line 242, in init_app
  File "socketio\base_server.py", line 34, in __init__
  File "engineio\base_server.py", line 94, in __init__
ValueError: Invalid async_mode specified

解决方案是在打包时指定下面参数：

sh 复制代码

--hidden-import="gevent" --hidden-import="geventwebsocket" --hidden-import="gevent.ssl" --hidden-import="gevent.builtins" --hidden-import="engineio.async_drivers.threading"

该解决方案之所以有效，是因为它精准地解决了 PyInstaller 打包 Flask-SocketIO 应用时的依赖分析缺陷。具体原理如下：

1. 根本原因分析

Flask-SocketIO 在运行时动态选择异步模式（async_mode），主要支持：

gevent（默认）
threading
eventlet

当 PyInstaller 打包时：

静态分析局限：PyInstaller 只能静态分析代码中的显式导入，无法检测动态加载的模块
隐式依赖缺失 ：gevent 和 engineio.async_drivers.threading 等关键模块是 Flask-SocketIO 运行时动态加载的，PyInstaller 默认不会打包它们
SSL/内置函数依赖 ：gevent 需要 SSL 支持和内置函数重定向（如 gevent.builtins）

2. 解决方案为何有效

通过在 hiddenimports 中显式声明这些模块：

python 复制代码

hiddenimports=[
    "gevent",                    # 核心协程库
    "geventwebsocket",           # WebSocket 支持
    "gevent.ssl",                # SSL 加密支持
    "gevent.builtins",           # 替换 Python 内置函数
    "engineio.async_drivers.threading"  # 强制指定线程模式驱动
]

每个模块的作用：

模块	作用	必要性
`gevent`	提供协程支持	必需
`geventwebsocket`	WebSocket 协议实现	必需
`gevent.ssl`	加密通信支持	在 HTTPS 场景必需
`gevent.builtins`	替换 `socket` 等内置函数	避免协程阻塞
`engineio.async_drivers.threading`	明确线程模式驱动	解决 `Invalid async_mode` 错误

3. 为什么开发环境能运行而打包后失败？

开发环境：所有依赖已安装，Python 可以动态加载任何模块
打包环境：PyInstaller 只打包它检测到的显式依赖，动态加载的模块会丢失

4. 技术深度：Flask-SocketIO 的异步模式选择

当代码调用 SocketIO(app) 时：

尝试加载 gevent（默认优先）
如果失败，尝试 eventlet
最后回退到 threading

打包后的问题：

PyInstaller 未打包 gevent → 尝试回退到 threading
但 engineio.async_drivers.threading 也未打包 → 彻底失败

总结

该解决方案通过强制声明这些动态加载的模块，完美填补了 PyInstaller 静态分析的盲区。这是处理 Python 动态导入系统与静态打包工具冲突的经典案例。

参考：

Pyinstaller 打包flask_socketio为exe程序后出现：ValueError: Invalid async_mode specified_flask 添加socketio后pyinstall 打包后不能运行-CSDN博客