Python ASGI 服务器 uvicorn 极简实战指南

• main: 你的 Python 文件名（不含 .py）。
• app: 文件中实例化的对象名（例如 app = FastAPI()）。
• --reload: 开发模式神器。代码修改后自动重启服务器，无需手动停止进程。

脚本方式

如果你希望直接在 Python 文件中启动服务（方便调试）：

# main.py 文件底部
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return "OK"

if __name__ == "__main__":
    # 等同于命令行：uvicorn main:app --reload
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

运行方法：python main.py

常用参数速查

这些参数基本能覆盖 80% 的场景：

注意： --workers 和 --reload 互斥，不能同时使用。

生产环境部署建议

在生产环境中（Linux），通常不直接裸跑 Uvicorn，而是使用 Gunicorn 作为进程管理器来管理 Uvicorn 的 Worker，以获得更好的稳定性和性能。

安装 Gunicorn:

pip install gunicorn

运行命令:

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

• -w 4: 开启 4 个 Worker 进程。
• -k ...: 指定使用 Uvicorn 的 Worker 类。

进阶：uvloop 原理与优化

什么是 uvloop？

一句话介绍：它是 Python 标准库 asyncio 的高性能替代品。

• 核心： 基于 libuv（Node.js 也在用这个库）构建。
• 效果： 让 Python 的异步代码运行速度提高 2-4 倍，性能直逼 Go 和 Node.js。
• 适用： Linux 和 macOS（不支持 Windows）。

如何使用

使用非常简单，只需要添加两行代码：引入库，然后调用 install()。

import asyncio
import uvloop

async def main():
    print("Hello, uvloop!")
    await asyncio.sleep(1)
    print("Done.")

if __name__ == "__main__":
    # 安装 uvloop 策略
    # 这行代码会将 asyncio 的默认事件循环替换为 uvloop
    uvloop.install()
    asyncio.run(main())

Web 框架中使用： 如果你是做 Web 开发（FastAPI, Sanic, Django 等），通常不需要手动写代码。

• Sanic: 默认内置并使用 uvloop。
• Uvicorn (FastAPI 的默认服务器): Uvicorn 默认就会检测并使用 uvloop。只要你安装了它，Uvicorn 就会自动启用。

# 只要安装了 uvloop，启动时不需要额外配置
pip install uvloop
uvicorn main:app

如果想强制使用或禁用： uvicorn main:app --loop uvloop 或 --loop asyncio。

为什么 uvloop 更快？

uvloop 之所以快，并不是因为它使用了什么魔法，而是因为它通过 Cython 将 Python 标准库 asyncio 的核心逻辑（事件循环）用 C 语言 重新写了一遍，底层则由高性能的 libuv 驱动。

可以将它的原理拆解为三个核心支柱：

1. 核心引擎：libuv

libuv 是 Node.js 的核心异步 I/O 库。它在 Linux 上使用 epoll，在 macOS 上使用 kqueue，这些是操作系统能够提供的最高效的 I/O 通知机制。

2. 桥梁技术：Cython

uvloop 是用 Cython 编写的扩展模块。它完全替换了 asyncio.AbstractEventLoop 接口的实现，绕过了 Python 解释器的部分开销。整个事件循环的'心跳'是在 C 语言层面运行的。

3. 性能优化的细节

• 零损耗的内存管理： 使用 Free list 技术重用内存，减少 GC 压力。
• 函数调用开销最小化： 内部处理尽可能保持在 C 层面流转。
• 高效的句柄管理： 针对不同类型的 I/O 进行了专门的优化路径。

常见坑点

1. 操作系统限制： uvloop 不支持 Windows。如果在 Windows 上开发，请使用标准 asyncio，部署到 Linux 服务器时再安装 uvloop。
2. 设置时机： 要在创建事件循环之前设置好（如程序入口最早发生）。
3. Jupyter 环境： 在 Notebook 中已有 Event Loop 运行时，直接 uvloop.install() 可能会报错，通常建议在生产代码中加上兼容处理。

try:
    import uvloop
    uvloop.install()
except ImportError:
    pass  # Windows 下没有 uvloop，回退到标准 asyncio

总结

开发用 uvicorn main:app --reload，生产用 Gunicorn 带 Uvicorn Worker。对于高并发网络 I/O 场景，确保安装 uvloop 能让服务性能提升一个台阶。