FastAPI环境搭建与项目初始化

📂 所属阶段：第一阶段 — 快速筑基（基础篇）
🔗 相关章节：FastAPI简介与优势 · Hello-World应用

快速开始前置检查

FastAPI 对系统要求极低且宽泛，入门门槛非常友好。

软硬件/系统最低标准

操作系统：Windows 7+ / macOS 10.12+ / 任意主流 Linux
Python：3.7+（推荐 3.10/3.11/3.12 最新稳定版）
硬件：2GB RAM、500MB 可用空间、现代 CPU

本地环境快速扫盲

先打开终端（Windows 用 PowerShell/CMD，Mac/Linux 用 Terminal），确认基础工具：

# 优先看是否有python3/pip3
python3 --version  # Mac/Linux，显示类似 Python 3.12.3
python --version   # Windows/部分配置过的Mac/Linux
pip3 --version     # 同理查包管理工具
pip --version

如果未安装/版本过低，请参考：

Windows：去 Python官网下载最新版，务必勾选「Add Python to PATH」
Mac：推荐 brew install python3
Linux：用对应包管理器（如 Ubuntu 的 sudo apt install python3 python3-pip）

扫盲后别忘了升级 pip 到最新稳定版：

# Windows/Mac/Linux 通用（推荐，避免权限/调用混乱）
python3 -m pip install --upgrade pip

隔离环境：Python虚拟环境

强烈建议全程使用虚拟环境开发！ 它能解决不同项目的包冲突、版本混乱、权限依赖问题。

方案选择：优先用官方内置 venv

Python 3.3+ 自带 venv，无需额外安装，够用且稳定。

创建并激活虚拟环境

# 1. 找个合适的位置创建项目文件夹，进入
mkdir my-fastapi-demo
cd my-fastapi-demo

# 2. 创建名为 venv 的虚拟环境（Windows/Mac/Linux 通用，用当前环境的python3）
python3 -m venv venv

# 3. 激活虚拟环境（关键：区分系统，激活后前面有(venv)）
# Windows PowerShell/CMD
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate

虚拟环境基础管理

# 退出虚拟环境（无论在哪都可以用）
deactivate

# 删除虚拟环境（彻底清空，直接删文件夹）
rm -rf venv  # Mac/Linux
rmdir /s venv  # Windows CMD

核心组件：FastAPI与Uvicorn

FastAPI 本身是 Web 框架，但需要一个 ASGI 服务器来处理网络请求，官方推荐 Uvicorn。

安装方式：按需选择

# 基础版：只装框架+标准Uvicorn（带 websocket、static 支持）
pip install fastapi uvicorn[standard]

# 完整版：直接装框架+所有官方推荐依赖（form、模板、环境变量、邮箱验证等）
pip install "fastapi[all]"

# （可选）安装特定版本（避免未来API变动）
pip install fastapi==0.110.0 uvicorn[standard]==0.29.0

用 requirements.txt 锁定依赖

把当前环境的所有包版本保存下来，方便共享/部署：

# 导出当前依赖
pip freeze > requirements.txt

其他人拿到项目后，安装依赖只需一行：

pip install -r requirements.txt

标准项目结构搭建

合理的项目结构能提升代码可读性、可维护性，也为后续模块化、分层架构做准备。

我的推荐结构（中大型项目也能扩展）

my-fastapi-demo/
├── app/                    # 核心应用代码
│   ├── __init__.py         # 标识这是个Python包
│   ├── main.py             # 应用入口、路由挂载、全局配置
│   ├── api/                # API路由层（可分v1/v2/v3）
│   │   ├── __init__.py
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── hello.py
│   ├── schemas/            # Pydantic数据验证模型（请求/响应体）
│   │   ├── __init__.py
│   │   └── common.py
│   ├── config/             # 项目配置（环境变量、Pydantic配置类）
│   │   ├── __init__.py
│   │   └── settings.py
│   └── utils/              # 通用工具类（日志、加密、工具函数）
│       └── __init__.py
├── tests/                  # 单元/集成测试代码
│   ├── __init__.py
│   └── test_hello.py
├── venv/                   # 虚拟环境（自动生成，别上传git）
├── requirements.txt        # 生产依赖（刚才生成的）
├── .gitignore              # Git忽略文件（后面会写）
└── README.md               # 项目说明文档

初始化核心文件

1. `.gitignore`（必须第一个写！）

防止把虚拟环境、缓存、配置中的敏感信息上传到 Git：

# 虚拟环境
venv/
env/

# Python缓存
__pycache__/
*.pyc
*.pyo
*.pyd

# IDE
.vscode/
.idea/

# 环境变量（敏感！）
.env
.env.local

2. `app/main.py`（应用入口）

from fastapi import FastAPI

app = FastAPI(
    title="我的FastAPI演示项目",
    description="这是一个用于演示环境搭建的标准FastAPI项目",
    version="0.1.0",
    openapi_url="/api/v1/openapi.json",  # 指定OpenAPI地址
    docs_url="/api/docs",  # Swagger UI文档地址（改短了）
    redoc_url="/api/redoc" # ReDoc文档地址
)

# 根路径测试
@app.get("/")
async def root():
    return {"message": "欢迎来到FastAPI演示项目！"}

# 健康检查接口（部署时常用）
@app.get("/health")
async def health_check():
    return {"status": "ok", "service": "FastAPI"}

VS Code开发工具配置

VS Code 是 FastAPI 开发的首选编辑器，以下配置能大幅提升开发效率：

1. 安装必要插件

打开 VS Code 左侧「扩展」，搜索并安装：

Python（官方必装，语法高亮、调试、代码补全）
Pylance（官方推荐，更好的类型提示）
Ruff（轻量级 Python 代码检查+格式化，替代 Black+Flake8+Isort）

2. 项目级配置

在项目根目录创建 .vscode/settings.json，覆盖全局配置，统一团队规范：

{
    // 绑定当前项目的虚拟环境Python解释器
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    // Windows下替换为：
    // "python.defaultInterpreterPath": "${workspaceFolder}\\venv\\Scripts\\python.exe",
    
    // 启用代码检查和格式化
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.formatting.provider": "ruff",
    
    // 保存时自动格式化、修复导入顺序
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": true
    }
}

一键验证开发环境

现在所有东西都准备好了，用一行命令启动应用试试：

启动应用（开发模式）

# 在项目根目录（激活虚拟环境后）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

参数说明：

app.main:app：模块路径app.main + FastAPI实例名app
--reload：开发模式专用，修改代码后自动重启
--host 0.0.0.0：允许局域网内其他设备访问（可选）
--port 8000：指定端口（默认就是8000，可选）

验证访问

启动成功后，打开浏览器访问以下任意地址：

主页面：http://127.0.0.1:8000/ → 看根路径返回的JSON
健康检查：http://127.0.0.1:8000/health → 看状态
Swagger UI（交互式文档）：http://127.0.0.1:8000/api/docs → 点「Try it out」测试接口
ReDoc（更美观的静态文档）：http://127.0.0.1:8000/api/redoc

高频踩坑指南

1. Windows PowerShell 激活虚拟环境报错

错误：无法加载文件，因为在此系统上禁止运行脚本
解决：以管理员身份打开 PowerShell，输入：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新激活即可。

2. 端口被占用

错误：OSError: [Errno 48] Address already in use
解决：

方案1：换端口启动：uvicorn app.main:app --port 8001
方案2：杀掉占用8000端口的进程（不推荐新手）

3. 找不到模块 app

错误：ModuleNotFoundError: No module named 'app'
解决：确保你是在项目根目录（my-fastapi-demo）启动的应用，别进到app目录里。

总结

恭喜你！FastAPI 的标准开发环境已经搭建完成，现在可以：

先看 Hello-World应用写第一个有功能的接口
熟悉 Swagger UI 交互式文档
开始探索 FastAPI 的其他特性了！

- 全程在虚拟环境中操作 - 及时更新 requirements.txt - 用 .env 管理敏感配置（别上传git）

#FastAPI环境搭建与项目初始化

#目录

#快速开始前置检查

#软硬件/系统最低标准

#本地环境快速扫盲

#隔离环境：Python虚拟环境

#方案选择：优先用官方内置 venv

#创建并激活虚拟环境

#虚拟环境基础管理

#核心组件：FastAPI与Uvicorn

#安装方式：按需选择

#用 requirements.txt 锁定依赖

#标准项目结构搭建

#我的推荐结构（中大型项目也能扩展）

#初始化核心文件

#1. .gitignore（必须第一个写！）

#2. app/main.py（应用入口）

#VS Code开发工具配置

#1. 安装必要插件

#2. 项目级配置

#一键验证开发环境

#启动应用（开发模式）

#验证访问

#高频踩坑指南

#1. Windows PowerShell 激活虚拟环境报错

#2. 端口被占用

#3. 找不到模块 app

#总结