使用--factory是因为它支持根据环境变量等动态创建ASGI应用实例,而main:app是硬编码、无法动态适配;工厂函数需为无参同步函数,返回ASGI应用对象。

为什么用 --factory 而不是直接写 main:app
当你需要根据环境变量、配置文件或运行时条件动态生成 ASGI 应用实例时,硬编码 main:app 就会失效。比如开发环境用 SQLite、生产环境切 PostgreSQL,或者要注入不同 logger 实例——这些都得在应用创建那一刻决定,而不是导入模块时就固化。工厂模式就是为这种“延迟创建 + 条件分支”设计的。
--factory 的调用逻辑和函数签名要求
Uvicorn 会把传入的工厂路径(如 main:create_app)当作一个可调用对象,执行它并期望返回一个 ASGI 应用实例(Callable[[dict, Callable, Callable], Awaitable[None]])。它不关心你内部怎么写,但必须满足两点:
- 函数必须是同步的(不能用
async def),因为 Uvicorn 在事件循环启动前就要拿到应用对象 - 函数不能带参数(Uvicorn 不支持传参调用),所有配置需通过环境变量、全局配置模块或闭包捕获
- 返回值必须是有效的 ASGI app —— 比如
FastAPI()、Starlette()实例,或自定义的async def app(...)函数
示例:main.py 中写:
import os
from fastapi import FastAPI
def create_app():
app = FastAPI()
env = os.getenv("ENV", "dev")
if env == "prod":
app.title = "Prod API"
else:
app.debug = True
return app
然后启动:uvicorn --factory main:create_app --env-file .env。注意:环境变量要在工厂函数里读,不是在顶层模块里读。
工厂模式下 --reload 和 --workers 的兼容性陷阱
工厂函数每次被调用都会新建一个应用实例。这在 --reload 模式下完全没问题(进程重启,重新导入+调用),但在多进程模式(--workers > 1)下容易踩坑:
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 每个 worker 进程都会独立调用一次工厂函数,所以数据库连接池、全局缓存、单例 logger 等资源若在工厂内初始化,就会重复创建,可能引发连接数超限或状态不一致
- 如果工厂函数里做了耗时操作(如加载大模型、预热缓存),多进程启动会明显变慢,且无共享机制
-
--reload和--workers不能共存 —— Uvicorn 显式禁止,报错信息是:AssertionError: --reload and --workers cannot be used together
真正需要多进程 + 工厂模式时,建议把初始化逻辑拆到工厂外(例如用模块级惰性初始化),或改用配置文件方式统一管理启动参数。
工厂函数与 Config 类、uvicorn_config.py 的协作边界
工厂函数只负责创建应用实例;其他启动配置(如端口、日志、事件循环)仍由 Uvicorn 的 Config 类接管。这意味着你不能在工厂函数里改 host 或 loop —— 那些属于服务器层,不是应用层。
常见混淆点:
- 误以为
--factory可以替代--config-file:其实二者正交,--config-file控制服务器行为,工厂控制应用构建 - 在工厂里调用
uvicorn.run(...):这是反模式,会导致嵌套启动,崩溃或死锁 - 用工厂返回一个配置字典而非 ASGI app:Uvicorn 会直接报
TypeError: expected an ASGI application
复杂项目中,推荐分层:工厂函数专注“我是什么应用”,uvicorn_config.py 专注“我怎么被运行”。两者配合才不容易漏掉关键配置项。










