FastAPIenvironment-setup与项目初始化

📂 所属阶段：第一阶段 — 快速筑基（基础篇）
🔗 相关章节：fastapi-intro-advantages · hello-world-app

快速开始前置检查

FastAPI 对机器的要求非常低，几乎任何能跑 Python 的电脑都能轻松上手。

基础软硬件要求

操作系统：Windows 7 及以上 / macOS 10.12 及以上 / 主流 Linux 发行版
Python 版本：3.7 以上（强烈推荐 3.10、3.11 或 3.12 最新稳定版）
硬件配置：2GB 内存、500MB 可用磁盘空间、任意现代 CPU

先看看你的电脑里有没有 Python

打开终端（Windows 用 PowerShell 或 CMD，Mac/Linux 用 Terminal），敲下面几条命令确认环境：

# Mac / Linux 一般用 python3
python3 --version   # 输出类似 Python 3.12.3
pip3 --version

# Windows 或配置过的系统可以直接用 python / pip
python --version
pip --version

如果提示“命令未找到”或版本太低，请根据你的系统安装或升级 Python：

Windows：访问 Python 官网下载安装包，安装时务必勾选「Add Python to PATH」
Mac：推荐使用 Homebrew 安装：brew install python3
Linux：使用自带的包管理器，例如 Ubuntu：sudo apt install python3 python3-pip

安装完成后，顺手把 pip 升到最新版，避免后续出现奇怪的兼容问题：

python3 -m pip install --upgrade pip   # 通用、安全的升级方式

隔离环境：Python虚拟环境

无论是练手项目还是正式产品，都强烈建议使用虚拟环境来开发！
虚拟环境能把不同项目所需的 Python 包隔离开，彻底解决“A 项目要用老版本，B 项目必须用新版本”这类冲突。

就用官方自带的 venv

Python 3.3 之后，标准库里就带了一个轻量虚拟环境工具 venv，不用额外安装任何东西。

创建并激活虚拟环境

# 1. 创建一个文件夹作为项目根目录，比如 my-fastapi-demo
mkdir my-fastapi-demo
cd my-fastapi-demo

# 2. 在项目里创建一个叫 venv 的虚拟环境
python3 -m venv venv

# 3. 激活虚拟环境（注意系统差别）
# Windows PowerShell / CMD：
venv\Scripts\activate
# Mac / Linux：
source venv/bin/activate

激活成功后，命令行前面会出现 (venv) 的标识，表示你已进入虚拟环境，后续所有 pip 安装都只会装在这个环境里。

常用管理命令

# 退出虚拟环境（回到系统全局 Python）
deactivate

# 彻底删除这个虚拟环境（直接把 venv 文件夹删掉就好）
rm -rf venv            # Mac / Linux
rmdir /s venv         # Windows CMD

核心组件：FastAPI与Uvicorn

FastAPI 本身是一个 Web 框架，负责定义接口、处理数据验证等；但它自己并不直接“跑”起来，需要一个 ASGI 服务器来接收网络请求，官方钦定的搭档就是 Uvicorn。

安装方式：按需选择

# 轻量安装：FastAPI + 标准版 Uvicorn（已包含 websocket、静态文件等支持）
pip install fastapi uvicorn[standard]

# 全家桶：一次性装齐官方推荐的所有扩展（表单处理、模板、环境变量、邮箱校验等）
pip install "fastapi[all]"

# 锁定版本：如果你希望现在写的代码以后不会因为依赖升级而出错，可以指定版本号
pip install fastapi==0.110.0 uvicorn[standard]==0.29.0

💡 建议：刚开始学习时用 fastapi[all] 很省心；进入生产项目时再用精确版本 + requirements.txt 来控制依赖。

用 requirements.txt 锁定环境

当你把项目分享给别人，或者在不同电脑上部署时，可以通过 requirements.txt 快速还原完全一致的环境。

# 导出当前虚拟环境中的所有包名和版本
pip freeze > requirements.txt

对方拿到项目后，只需要一行命令：

pip install -r requirements.txt

标准项目结构搭建

清晰的项目结构能让你在代码变多时也不慌张，同时为团队协作和功能扩展打下基础。

先把这些关键文件写好

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="这是一个用于演示environment-setup的标准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 是 Python / FastAPI 开发中最受欢迎的编辑器，装好下面几个插件并做一点配置，开发效率会提升一大截。

1. 必装插件

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

Python（官方的，提供语法高亮、调试、代码补全等基础功能）
Pylance（强大的类型检查和自动补全）
Ruff（一款极快的 Python 代码检查 + 格式化工具，可以同时替代 Flake8、isort 等）

2. 给项目加上本地配置

在项目根目录创建 .vscode/settings.json，内容如下：

{
    // 设置为当前项目里的虚拟环境 python 解释器
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    // Windows 下请用下面路径：
    // "python.defaultInterpreterPath": "${workspaceFolder}\\venv\\Scripts\\python.exe",

    // 启用 Ruff 来做代码检查与格式化
    "python.linting.enabled": true,
    "python.linting.ruffEnabled": true,
    "python.formatting.provider": "ruff",

    // 保存文件时自动整理格式和修复导入
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": true
    }
}

这样，团队里每个人都能用统一的规则写代码，减少“格式化战争”。

一键验证开发环境

所有零件都准备好之后，用下面这条命令启动你的第一个 FastAPI 应用：

# 确保在项目根目录，且虚拟环境已激活
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

参数解释：

app.main:app → 模块路径 app/main.py 里的 FastAPI 实例 app
--reload → 代码一修改就自动重启，适合开发调试
--host 0.0.0.0 → 允许同一局域网内的其他设备访问（如果只想本机访问，可以去掉或者用 127.0.0.1）
--port 8000 → 监听 8000 端口（不写的话默认也是 8000）

打开浏览器，看看效果

服务启动后，在浏览器里输入以下地址：

根路径：http://127.0.0.1:8000/ → 返回 {"message": "欢迎来到FastAPI演示项目！"}
健康检查：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

全部能正常访问的话，恭喜你，FastAPI 开发environment-setup成功！

高频踩坑指南

1. Windows 上激活虚拟环境时报“无法加载文件…”

错误信息：无法加载文件 ...，因为在此系统上禁止运行脚本
解决办法：用管理员身份打开 PowerShell，执行下面这行命令，然后重新激活：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

2. 启动时提示“Address already in use”

错误信息：OSError: [Errno 48] Address already in use
原因：8000 端口已经被其他程序占用了。
解决办法：换一个端口启动，比如 --port 8001，或者在终端里找到占用端口的程序并关掉它（新手建议直接换端口）。

3. 找不到 `app` 模块

错误信息：ModuleNotFoundError: No module named 'app'
常见原因：你没有在项目根目录（my-fastapi-demo）运行命令，而是错误地进入了 app 文件夹。
正确做法：确保在 my-fastapi-demo 这一层启动，那个目录下应该有 app 文件夹和 venv 文件夹。

4. 明明安装了包，运行时却说找不到

多半是因为虚拟环境没有激活。每次打开新终端，记得先激活虚拟环境（看到命令前有 (venv) 标志），再运行项目。

总结

现在你已经拥有一个干净、专业的 FastAPI 开发环境，下一步可以：

跟着 hello-world-app 写第一个能接收参数、返回数据的接口；
多玩玩自带的 Swagger UI 交互式文档，体验一键调试的快感；
按照这个项目结构，开始搭建你自己的功能模块。

- 始终在虚拟环境中操作，别污染系统 Python 环境 - 每次装新包后，记得更新 `requirements.txt` - 敏感配置（密码、密钥）放在 `.env` 文件里，并把它加入 `.gitignore`

#FastAPIenvironment-setup与项目初始化

#目录

#快速开始前置检查

#基础软硬件要求

#先看看你的电脑里有没有 Python

#隔离环境：Python虚拟环境

#就用官方自带的 venv

#创建并激活虚拟环境

#常用管理命令

#核心组件：FastAPI与Uvicorn

#安装方式：按需选择

#用 requirements.txt 锁定环境

#标准项目结构搭建

#推荐的项目布局（轻松扩展为大型项目）

#先把这些关键文件写好

#1. .gitignore（防止把垃圾文件上传到 Git）

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

#VS Code开发工具配置

#1. 必装插件

#2. 给项目加上本地配置

#一键验证开发环境

#打开浏览器，看看效果

#高频踩坑指南

#1. Windows 上激活虚拟环境时报“无法加载文件…”

#2. 启动时提示“Address already in use”

#3. 找不到 app 模块

#4. 明明安装了包，运行时却说找不到

#总结