VS Code 开发 FastAPI – 菜鸟教程-菜鸟网博客-为草根创业提供网络知识

在 VS Code 中开发 FastAPI 是一种极其高效的体验。VS Code 提供了顶级的 Python 支持、无缝的调试功能以及丰富的生态插件。

下面我将为你提供一份从零开始的 VS Code + FastAPI 终极配置指南，涵盖环境搭建、调试配置、代码规范和 API 测试，帮你打造最舒适的开发工作流。

🛠️ 第一步：项目初始化与虚拟环境

永远不要在全局环境中开发。打开终端，在你的项目目录下执行：

# 1. 创建虚拟环境 (命名为 .venv)
python -m venv .venv

# 2. 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

# 3. 安装核心依赖
pip install fastapi uvicorn[standard] pydantic

🧩 第二步：安装必备的 VS Code 扩展

打开 VS Code 的扩展面板 (Ctrl+Shift+X 或 Cmd+Shift+X)，搜索并安装以下扩展：

Python (by Microsoft)：核心扩展，提供解释器管理、调试支持。
Pylance (by Microsoft)：提供极速的类型检查、智能提示和代码补全（通常安装 Python 扩展时会自动带上）。
Ruff (by Astral Software)：目前最快、最现代的 Python Linter 和格式化工具（替代 Flake8 + Black）。
Thunder Client 或 REST Client：直接在 VS Code 内测试 API，无需切换到浏览器或 Postman。

⚙️ 第三步：关键配置（新手最容易卡住的地方）

1. 选择正确的 Python 解释器

这是确保 VS Code 能识别 fastapi 模块的关键。

按下 Ctrl+Shift+P (Windows) 或 Cmd+Shift+P (macOS) 打开命令面板。
输入并选择 Python: Select Interpreter。
在列表中选择你刚才创建的虚拟环境（通常路径末尾会显示 .venv 或 venv）。
(右下角的状态栏也会显示当前选择的 Python 版本，点击它也可以快速切换)。

2. 配置自动格式化 (Ruff)

在项目根目录创建或修改 .vscode/settings.json 文件，让代码在保存时自动格式化：

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },
  "python.analysis.typeCheckingMode": "basic"
}

🐛 第四步：配置一键调试 (Debugging)

不要只用 print 调试！VS Code 的可视化调试器是排查 FastAPI 问题的神器。

在项目根目录创建一个文件夹 .vscode，并在其中新建文件 launch.json。
粘贴以下配置（专为 Uvicorn + FastAPI 优化）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "FastAPI: Debug",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "main:app",
        "--host", "0.0.0.0",
        "--port", "8000",
        "--reload"
      ],
      "jinja": true,
      "justMyCode": true,
      "env": {
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  ]
}

如何使用：

在 main.py 的某行代码左侧点击，打上一个红点（断点）。
按下 F5 或点击左侧活动栏的“运行和调试”图标，选择 FastAPI: Debug。
当你在浏览器或测试工具中请求该接口时，代码会在红点处暂停，你可以查看变量值、调用堆栈，甚至实时修改变量。

🧪 第五步：在 VS Code 内直接测试 API

无需离开编辑器，推荐使用 REST Client 扩展来测试接口。

在项目根目录创建一个文件 test.http (后缀必须是 .http)。
写入以下测试用例：

### 1. 测试根路径
GET http://127.0.0.1:8000/

### 2. 测试带参数的路径
GET http://127.0.0.1:8000/items/42?q=hello

### 3. 测试 POST 请求 (发送 JSON)
POST http://127.0.0.1:8000/users/
Content-Type: application/json

{
    "username": "alice",
    "email": "alice@example.com",
    "age": 25
}

点击每段请求上方的 Send Request 绿色小三角，响应结果会直接在右侧分屏显示，极其高效！

💡 第六步：提升效率的进阶技巧

1. 使用代码片段 (Snippets)

如果你经常写 FastAPI 路由，可以自定义代码片段。
打开命令面板 -> Preferences: Configure User Snippets -> 选择 python.json，添加：

"FastAPI Router": {
  "prefix": "fapi",
  "body": [
    "@app.${1|get,post,put,delete|}(\"/${2:path}\")",
    "def ${3:handler_name}():",
    "    ${4:return {\"message\": \"ok\"}}",
    ""
  ],
  "description": "FastAPI route template"
}

现在在 Python 文件中输入 fapi 并按 Tab，就能快速生成路由模板。

2. 利用 Pylance 的类型提示

FastAPI 的强大之处在于类型提示。确保你的 Pydantic 模型和函数参数都有明确的类型标注，Pylance 会在你写错类型时立刻画出红色波浪线，并在鼠标悬停时显示详细的类型信息。

3. 排除虚拟环境文件夹

为了避免 VS Code 搜索或索引虚拟环境中的海量文件导致卡顿，在项目根目录创建 .vscode/settings.json 并添加：

{
  "files.watcherExclude": {
    "**/.venv/**": true
  },
  "search.exclude": {
    "**/.venv": true
  }
}

🚨 常见避坑指南

报错 ModuleNotFoundError: No module named 'fastapi'

原因：VS Code 终端或调试器使用的是系统全局 Python，而不是你的 .venv。
解决：检查右下角的 Python 解释器是否选对了 .venv；如果是终端报错，请确保终端提示符前有 (.venv)，如果没有，请重新运行激活命令。

调试时断点不生效（变成空心圆）

原因：使用了 --reload 参数时，Uvicorn 会启动多个进程，调试器可能附加到了错误的子进程上。
解决：在 launch.json 中，确保配置正确。如果仍有问题，可以尝试在开发调试时暂时去掉 --reload，或者使用 justMyCode: false（不推荐，会进入第三方库源码）。

端口 8000 被占用

解决：在 launch.json 的 args 中将 "--port", "8000" 改为 "8001"，或者在终端运行 lsof -i :8000 (macOS/Linux) / netstat -ano | findstr :8000 (Windows) 杀掉占用进程。

按照这套配置，你的 VS Code 将变成一个专为 FastAPI 打造的“重型武器”：写代码有极速提示，保存时自动排版，按 F5 即可断点调试，按一个按钮就能测试 API。

如果你在配置过程中遇到任何报错（比如 launch.json 不生效，或者扩展冲突），随时把错误信息发给我，我帮你排查！