python怎么启用uvicorn服务器

前提条件

首先，你需要安装 Uvicorn。如果你的项目是基于 FastAPI 的，通常 FastAPI 的依赖中已经包含了 Uvicorn，但单独安装它也总是个好习惯。

# 使用 pip 安装
pip install "uvicorn[standard]"

# 强烈推荐安装 [standard] 版本，它包含了额外的依赖
# 可以提供更好的性能和功能，如自动重载、HTTP/2 等。

为什么推荐 uvicorn[standard]？
它会自动安装 httptools 和 uvloop（在 Linux 和 macOS 上），这些库能显著提升 Uvicorn 的性能。

---

第一步：创建一个简单的 Web 应用

在启动服务器之前，你需要一个可以被 Uvicorn 运行的 Web 应用。这里我们用最流行的 FastAPI 框架来创建一个简单的 “Hello World” 应用。

1. 创建一个 Python 文件，例如 main.py。
2. 在 main.py 中写入以下代码：

# main.py
from fastapi import FastAPI

# 创建一个 FastAPI 应用实例
app = FastAPI()

# 定义一个根路径 "/" 的 GET 请求处理函数
@app.get("/")
async def read_root():
    return {"Hello": "World"}

# 定义一个路径 "/items/{item_id}" 的 GET 请求处理函数
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

现在，你有了一个基本的 FastAPI 应用。接下来，我们用 Uvicorn 来运行它。

---

第二步：使用命令行启动 Uvicorn 服务器

这是最常用、最直接的方式。打开你的终端（或命令提示符），切换到 main.py 文件所在的目录，然后运行以下命令：

基础命令格式

uvicorn <模块名>:<应用实例名>

• <模块名>：你的 Python 文件名，不包含 .py 后缀。例如，main.py 的模块名就是 main。
• <应用实例名>：在你的 Python 文件中，FastAPI 或 Starlette 应用实例的变量名。在我们的 main.py 中，这个变量名是 app。

针对我们的 main.py 的启动命令

uvicorn main:app

运行这个命令后，你会看到类似下面的输出：

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

现在，你的服务器已经成功启动了！

• 你可以打开浏览器，访问 http://127.0.0.1:8000，你将看到 {"Hello": "World"}。
• 访问 http://127.0.0.1:8000/items/5?q=somequery，你将看到 {"item_id": 5, "q": "somequery"}。

---

第三步：常用的 Uvicorn 启动参数

Uvicorn 提供了许多有用的命令行参数来控制服务器的行为。

1. --host 和 --port：指定主机和端口

默认情况下，Uvicorn 只在本地（127.0.0.1）的 8000 端口上运行。如果你想让局域网内的其他设备也能访问你的服务，或者想使用其他端口，可以使用这两个参数。

# 让服务器在所有网络接口上监听，并使用 9000 端口
uvicorn main:app --host 0.0.0.0 --port 9000

• --host 0.0.0.0：表示监听所有可用的网络接口，这样同一网络下的其他电脑或手机就可以通过你的 IP 地址访问这个服务了。
• --port 9000：将服务端口从默认的 8000 改为 9000。

2. --reload：启用自动重载

这是开发阶段最重要的参数！启用后，当你修改并保存了你的 Python 代码文件时，Uvicorn 会自动重启服务器，加载最新的代码。你无需手动停止和重新启动服务器，极大地提高了开发效率。

uvicorn main:app --reload

注意：在生产环境中，不要使用 --reload，因为它会消耗额外的资源并可能影响稳定性。

3. --workers：指定工作进程数量

Uvicorn 默认是单进程运行的。为了充分利用多核 CPU 的性能，在生产环境中，你可以使用 --workers 参数来启动多个工作进程。

# 启动 4 个工作进程
uvicorn main:app --workers 4

提示：通常，工作进程的数量可以设置为 CPU 核心数 + 1。--workers 不能与 --reload 同时使用。

4. --log-level：设置日志级别

你可以控制 Uvicorn 输出的日志信息的详细程度。

# 只显示 warning 和 error 级别的日志
uvicorn main:app --log-level warning

# 显示 debug 级别的日志，信息最详细
uvicorn main:app --log-level debug

---

第四步：在 Python 代码中直接启动 Uvicorn

虽然不常用，但有时你可能希望将 Uvicorn 的启动逻辑集成到你的 Python 脚本中，而不是通过命令行。这可以通过 uvicorn.run() 函数实现。

修改你的 main.py 文件：

# main.py
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"Hello": "World"}

# --- 这是新增的部分 ---
if __name__ == "__main__":
    # 在这里调用 uvicorn.run()
    # 参数与命令行参数一一对应
    uvicorn.run(
        "main:app",  # 模块名:应用实例名
        host="0.0.0.0",
        port=8000,
        reload=True  # 开发时启用自动重载
    )

现在，你可以直接像运行普通 Python 脚本一样启动服务器：

python main.py

Uvicorn 服务器就会以你指定的配置启动。这种方式对于创建可执行的脚本或进行某些自动化测试非常有用。

---

总结：开发 vs. 生产

场景	推荐命令	关键参数	说明
本地开发	uvicorn main:app --reload	--reload	自动重载是开发时的福音，能极大提升效率。
生产部署	uvicorn main:app --host 0.0.0.0 --port 80 --workers 4	--host, --port, --workers	多进程利用多核性能，监听 0.0.0.0 以便外部访问。通常还会配合一个进程管理器（如 Gunicorn）或反向代理（如 Nginx）使用。

希望这份详细的指南能帮助你顺利地使用 Uvicorn 启动你的 Python Web 服务器！如果你有更具体的问题，比如如何与 Nginx 配合部署，欢迎随时提问。