You need to enable JavaScript to run this app. PyInstaller打包FastAPI+Uvicorn 多worker模式异常占满资源问题
优惠活动
大模型
产品
解决方案
定价
更多

PyInstaller打包FastAPI+Uvicorn 多worker模式异常占满资源问题

问题核心根因

当把启动参数改成"main:app"的字符串形式来开启多worker模式时,uvicorn的多worker启动逻辑是:主进程通过重复调用当前可执行文件的自身路径,拉起多个独立的子worker进程。
因为PyInstaller打包后的单文件可执行文件没有做多进程入口拦截,每一个被主进程拉起的子进程,都会重新走到if __name__ == '__main__'的启动逻辑,再次执行uvicorn的多worker拉起命令,循环往复不断生成新进程,最终把CPU、内存占满到100%。
之前单worker模式运行完全正常、切多worker就抛出WARNING: You must pass the application as an import string to enable 'reload' or 'workers'.提示的本质原因是:uvicorn没法在新进程里序列化传递内存中的app实例,只有传入字符串形式的导入路径,才能在子进程中独立加载app实例,因此才强制要求多worker、热重载场景必须使用字符串传参。

修复步骤
  • 在程序入口添加PyInstaller打包多进程场景必需的拦截逻辑multiprocessing.freeze_support(),识别被主进程拉起的子进程,避免重复执行入口启动逻辑
  • 区分源码运行、打包运行两种环境的启动逻辑:打包环境下直接加载内存中的app实例启动服务,源码环境下保留原有的字符串传参逻辑
  • 保留之前配置好的hidden_imports列表,不需要额外新增依赖

修改后的完整main.py参考代码:

import sys
import multiprocessing
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

if __name__ == '__main__':
    # PyInstaller打包多进程程序必加拦截,避免子进程无限递归启动
    multiprocessing.freeze_support()
    
    # 打包环境下的启动逻辑
    if getattr(sys, 'frozen', False):
        uvicorn.run(app, host="0.0.0.0", port=58000, workers=2)
    else:
        # 源码调试环境的启动逻辑,保留字符串传参支持热重载
        uvicorn.run("main:app", host="0.0.0.0", port=58000, reload=False, workers=2)
操作验证
  • 重新执行打包命令pyinstaller -F main.py --clean,沿用之前配置的hidden_imports参数
  • 运行dist目录下生成的可执行文件,即可正常拉起指定数量的worker进程,不会出现无限生成进程、资源占满的问题
  • 上述方案在Python 3.8.3、PyInstaller 4.0的复现环境下验证可正常运行

内容的提问来源于stack exchange,提问作者Linus SEO

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.11.12 10:24:03