FastAPI 安装与虚拟环境配置指南

简介

在开始使用FastAPI开发Web应用之前，正确安装和配置开发环境至关重要。使用虚拟环境可以隔离项目依赖，防止不同项目间的包版本冲突。本教程将一步步指导你从零开始，安装FastAPI并设置虚拟环境，适合Python新手。

前置条件

确保满足以下条件，如果未安装，请先完成：

• Python 3.7 或更高版本：FastAPI需要较新的Python版本。可通过运行 python --version 或 python3 --version 检查当前版本。
• pip 包管理工具：通常随Python一起安装，可通过 pip --version 检查。

如果未安装Python，请访问 Python官网 下载并安装最新版本。安装时记得勾选“Add Python to PATH”选项。

步骤一：创建项目目录

首先，为你的FastAPI项目创建一个新目录，以保持文件整洁。

1. 打开终端（Windows上是命令提示符或PowerShell，macOS/Linux上是终端）。
2. 创建并进入目录：

   mkdir my_fastapi_project
   cd my_fastapi_project
   

步骤二：创建虚拟环境

虚拟环境是一个独立的Python环境，允许你在其中安装特定版本的包而不影响系统全局环境。

使用Python内置的venv模块

在项目目录中，运行以下命令创建虚拟环境：

python -m venv venv

或者使用 python3（如果系统中有多个Python版本）：

python3 -m venv venv

这将创建一个名为 venv 的文件夹，包含虚拟环境的所有文件。

步骤三：激活虚拟环境

激活虚拟环境后，所有pip安装的包将只安装在这个环境中。

根据你的操作系统，激活命令不同：

• Windows:

  venv\Scripts\activate
  

• macOS/Linux:

  source venv/bin/activate
  

激活后，终端提示符通常会显示虚拟环境名称，如 (venv)，表示你已进入虚拟环境。

步骤四：安装FastAPI和相关包

在激活的虚拟环境中，使用pip安装FastAPI和Uvicorn（一个ASGI服务器，用于运行FastAPI应用）。

1. 安装FastAPI：

   pip install fastapi
   

2. 安装Uvicorn：

   pip install uvicorn[standard]
   

   [standard] 选项安装额外的依赖，如WebSocket支持。

安装完成后，可以通过 pip list 查看已安装的包，确认FastAPI和Uvicorn已成功安装。

步骤五：验证安装

让我们创建一个简单的FastAPI应用来测试安装是否成功。

1. 在项目目录中，创建一个名为 main.py 的Python文件：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI!"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

2. 运行应用：

   uvicorn main:app --reload
   

   • main 指 main.py 文件。
   • app 指 FastAPI 实例。
   • --reload 选项启用热重载，代码更改后自动重启服务器，便于开发。

3. 打开浏览器，访问 http://127.0.0.1:8000。你应该看到JSON响应：{"message": "Hello, FastAPI!"}。

4. 访问 http://127.0.0.1:8000/items/1?q=test，测试动态路由和查询参数。

如果一切正常，说明FastAPI已成功安装并运行！

常见问题与解决

• 问题：pip命令未找到

  • 确保Python已正确安装并添加到系统PATH环境变量。重新安装Python或检查环境变量设置。

• 问题：虚拟环境激活失败

  • 检查路径是否正确，尤其是在Windows上，确保使用反斜杠。如果问题持续，尝试删除 venv 文件夹并重新创建。

• 问题：运行uvicorn时出错

  • 确认虚拟环境已激活，并安装了Uvicorn。可以通过 pip list | grep uvicorn（macOS/Linux）或 pip list | findstr uvicorn（Windows）检查。

• 退出虚拟环境

  • 完成后，可以运行 deactivate 命令退出虚拟环境。

下一步

现在你已经成功配置了FastAPI开发环境，可以：

• 学习FastAPI基础，如路由、请求和响应模型。
• 探索更多功能，如依赖注入、数据库集成。
• 阅读官方文档或后续教程，深入了解API开发。

总结

通过本教程，你学会了如何创建Python虚拟环境来管理依赖，并安装了FastAPI和Uvicorn。这为后续的FastAPI开发奠定了坚实的基础，确保项目环境干净、可控。记住，在开发新项目时，总是推荐使用虚拟环境来避免依赖冲突。

保持探索，享受FastAPI带来的快速开发体验！