Uvicorn 必须安装 uvicorn[standard] 才具备自动重载、uvloop 和 httptools 等核心功能；配置文件仅允许定义 uvicorn_config 字典，键名用下划线格式；--reload 与 --workers 不可共存。

Uvicorn 必须装 uvicorn[standard]，否则开发时缺自动重载、生产时少 uvloop 和 httptools，性能和体验直接打折。

安装必须用 standard 依赖

最小安装 pip install uvicorn 只有基础功能，--reload 会报错，websockets 不可用，Linux/macOS 下也跑不起来 uvloop。真正能用的只有：

• pip install "uvicorn[standard]"（注意引号，Windows 也要加）
• 它会自动装上 uvloop、httptools、websockets、watchfiles 等关键依赖
• 验证是否生效：运行 python -c "import uvloop, watchfiles, httptools"，无报错才算齐

配置文件里不能写 uvicorn.run()

用 --config-file 启动时，Uvicorn 会把配置文件当成纯数据模块加载。如果里面写了 uvicorn.run(...)，进程一启动就执行两次——一次是配置加载，一次是命令行触发，必然报错或卡死。

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

• 配置文件（如 uvicorn_config.py）只允许定义一个变量：uvicorn_config = {...}
• 键名必须转成下划线格式，比如命令行的 --host 0.0.0.0 对应 "host": "0.0.0.0"
• "app" 的值仍是字符串，如 "main:app"，不能写成 app = FastAPI() 这种表达式
• 启动命令必须带路径：uvicorn --config-file config/uvicorn_config.py，不支持自动查找

--reload 和 --workers 不能共存

这是最常踩的坑：开发时加了 --reload，顺手又加 --workers 4，结果 Uvicorn 直接退出，只打印一行 ERROR: --reload and --workers cannot be used together。

• --reload 是单进程 + 文件监听，靠 watchfiles 实现，多进程会冲突
• 生产环境要多进程，必须去掉 --reload，改用 --workers N（N ≥ CPU 核数）
• PyCharm 或 VS Code 调试时，别在运行配置里同时勾选 “启用重载” 和 “工作进程数”

配置文件路径、uvicorn_config 变量名、--reload 与 --workers 的互斥性——这三点出错时没明显提示，容易卡在“启动了但没反应”或“启动即退出”，得先盯住它们。