最常见原因是未安装 uvicorn[standard]，导致 UvicornWorker 类缺失；必须执行 pip install "uvicorn[standard]" 并验证 from uvicorn.workers import UvicornWorker 是否成功。
gunicorn -k uvicorn.workers.UvicornWorker 启动就报错
最常见原因是 uvicorn[standard] 没装全。只装 uvicorn 默认不带 Gunicorn 兼容层，UvicornWorker 类根本不存在，启动时会直接抛 ImportError: cannot import name 'UvicornWorker'。
必须用这个命令重装：
pip install "uvicorn[standard]"
注意引号不能少，否则 pip 可能忽略 extras 部分。装完后可验证：
python -c "from uvicorn.workers import UvicornWorker; print('OK')"
- 如果报错，说明没装对，别跳过这步
- 别用
uvicorn独立安装后再补装gunicorn——顺序不重要，但依赖必须完整 - 在 Docker 里部署时，确保
requirements.txt明确写成uvicorn[standard]，而不是只写uvicorn
workers 数设高了反而响应变慢
workers 是 Gunicorn 的进程数，不是并发连接数。每个 UvicornWorker 自身就能靠 asyncio 处理上千并发请求；盲目堆高 workers 会导致：
立即学习“Python免费学习笔记（深入）”；
- 进程调度开销上升，CPU 缓存失效加剧
- 内存占用线性增长（每个 worker 都载入完整应用+依赖）
- 文件描述符耗尽（尤其
keepalive开得大时）
推荐值不是拍脑袋定的：
- CPU 密集型（如 StructBERT 推理）：
workers = CPU核心数 - I/O 密集型（如调外部 API、数据库）：
workers = CPU核心数 × 2 - 混合型（如 FastAPI + SQLAlchemy + Redis）：从
CPU核心数 + 1开始压测，观察htop中 CPU idle 和 load average 平衡点
查当前 CPU 核数：
python -c "import multiprocessing; print(multiprocessing.cpu_count())"
服务启动后 CPU 空转但请求卡住
典型症状：top 显示 Python 进程 CPU 占用 90%+，但 curl http://localhost:8000 要等好几秒才返回，甚至超时。大概率是 worker_class 配错了。
Gunicorn 默认用 sync 工作类，它会把 ASGI 应用当同步函数调用，结果就是：
- async 路由函数被当成普通函数执行，
await不生效 - 整个事件循环被阻塞，所有请求排队等一个协程“跑完”
- 日志里可能出现
RuntimeWarning: coroutine 'app' was never awaited
必须显式指定：
- 命令行启动：加
-k uvicorn.workers.UvicornWorker（-k是--worker-class缩写） - 配置文件里：写
worker_class = "uvicorn.workers.UvicornWorker"，拼错一个字母（比如少个U或写成uvicor）都会退化为 sync - 别信网上抄来的
worker_class = "gevent"或"gthread"—— 那是给同步框架用的，跟 ASGI 不兼容
Uvicorn 自己的 --workers 参数还在用
只要用了 Gunicorn 调度，uvicorn 命令行参数就完全失效。如果你在 gunicorn 启动命令里还混着 uvicorn --workers 4，或者配置文件里写了 uvicorn_cmd_args = ["--workers", "4"]，会出现两种后果：
- 启动失败：
Address already in use（Gunicorn 和 Uvicorn 同时 bind 同一端口） - 静默异常：Uvicorn worker 内部又 fork 出子进程，导致嵌套多进程，资源争抢、信号处理混乱
正确做法只有一处控制权：
- 进程数量由 Gunicorn 的
-w或workers控制 - Uvicorn Worker 内部必须是单进程（即
uvicorn启动时不带--workers） - 所有网络参数（
--host/--port）都交给 Gunicorn 的-b或bind，Uvicorn 不参与绑定
简单记：Gunicorn 是老板，Uvicorn Worker 是打工仔；老板安排几个工位（workers），打工仔只管自己工位上的活，不插手招人和租办公室。
