uvicorn main:app是最简启动格式,要求main.py中定义app=FastAPI()且工作目录正确;常见错误包括ModuleNotFoundError(路径错)、AttributeError(变量名不匹配)及--reload与--workers互斥。

uvicorn main:app 是最简启动格式
只要你的 main.py 里有 app = FastAPI()(或 Starlette()),就能直接运行:uvicorn main:app。它默认绑定 127.0.0.1:8000,只允许本机访问。
常见错误现象:ModuleNotFoundError: No module named 'main' —— 很可能当前工作目录不是 main.py 所在目录;AttributeError: module 'main' has no attribute 'app' —— 变量名写成了 api 或 application,但命令里仍用 :app。
- 确保终端 pwd 是
main.py所在路径 - 检查
main.py中是否真的定义了名为app的变量(大小写敏感) - 不推荐全局安装
uvicorn,优先用python -m uvicorn main:app,避免 PATH 冲突
开发时加 --reload,但别在生产环境用
--reload 会让 Uvicorn 监听文件变化,一保存就自动重启。它只适用于本地开发,**不能和 --workers 共存**,也**绝对不能用于生产环境** —— 它会 fork 出多个进程监听文件,导致不可预测的资源竞争和日志混乱。
正确开发命令示例:python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
-
--host 0.0.0.0才能让局域网其他设备访问(比如手机连同一 WiFi 测试) - Windows 上如果提示端口被占,先试
netstat -ano | findstr :8000查 PID,再taskkill /PID xxx /F - PyCharm 运行配置中,“Module name” 填
uvicorn,“Parameters” 填main:app --reload即可,不用额外装 shell 命令
生产部署要换参数组合
生产环境必须关掉 --reload,改用 --workers 控制并发进程数。Uvicorn 本身是单进程异步模型,多进程靠 --workers 实现,推荐值为 CPU 核心数 × 2 + 1(比如 4 核机器设 --workers 9)。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
典型生产命令:uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 --log-level warning
-
--log-level warning可减少日志量,避免 I/O 拖慢响应 - 不要依赖
uvicorn直接扛高流量,真实生产通常套一层gunicorn(用uvicorn.workers.UvicornWorker),它更稳、支持平滑重启和负载均衡 -
--timeout-keep-alive 5可调低长连接超时,防止空闲连接堆积
路径写错会导致 ModuleNotFoundError
Uvicorn 加载应用分两种路径逻辑:带 __init__.py 的是模块路径(用点号分隔),否则是文件路径。比如项目结构是 src/api/main.py 且无 src/__init__.py,就不能写 src.api:app,得写 src/api:app。
安全做法是显式指定根目录:uvicorn --app-dir src api.main:app,这样无论你在哪执行命令都有效。
-
--app-dir优先级高于PYTHONPATH和当前目录,Docker 中尤其有用 - 如果用了工厂函数(如
def create_app() → FastAPI),必须加--factory参数:uvicorn main:create_app --factory - 配置文件方式虽存在(变量名必须叫
uvicorn_config),但实际项目中远不如.env+ 命令行参数灵活
配置项之间有硬性互斥关系,比如 --reload 和 --workers 同时出现会直接报错退出,而不是静默忽略 —— 这个细节很多人第一次部署生产时才意识到。

















