能直接跑通 FastAPI 的最小 VSCode 配置只需 Python（安装时勾选 Add to PATH）、Python、Pylance 和 FastAPI Snippets 扩展，关键在激活虚拟环境、确保 main.py 中有顶层 app 变量、终端位于项目根目录，并用 uvicorn main:app --reload 启动；调试需配置 launch.json 使用 module: "uvicorn"。
能直接跑通 FastAPI 的最小 VSCode 配置，只用装 Python、Python 扩展、Pylance 和 uvicorn，其他都可延后。最常卡住的不是代码，而是终端没激活虚拟环境或 uvicorn 命令找不到 app 变量名。
Python 安装必须勾选 Add Python to PATH
不勾这个选项，VSCode 终端里敲 python --version 会报“命令未找到”。Windows 用户尤其容易漏掉——安装器默认不勾，得手动点；macOS/Linux 一般自带或通过 brew install python 安装，PATH 通常没问题。验证方式很简单：
- 打开系统终端（不是 VSCode 内置终端），运行
python --version，看到Python 3.9.10或更高即可 - 再运行
pip --version，确认 pip 已就位 - 如果失败，别急着重装，先查环境变量：Windows 运行
echo %PATH%，看输出里有没有 Python 安装路径；macOS/Linux 运行echo $PATH
VSCode 必装扩展只有三个：Python、Pylance、FastAPI Snippets
Python（Microsoft）是基础，提供调试和语法高亮；Pylance 是语言服务器，没它的话类型提示、跳转定义基本失效；FastAPI Snippets 虽非必需，但写 @app.get、Depends 时按 Tab 就补全，省去手敲拼错。注意：
- 装完扩展后必须重启 VSCode，否则
main.py文件可能仍被识别为纯文本 - 不要装“Python for VSCode”“PyCharm Keymap”这类混淆名称的第三方扩展，容易冲突
- 如果打开
main.py后左下角没显示 Python 解释器路径（如./.venv/bin/python），说明解释器没选对：按Ctrl+Shift+P→ 输入 “Python: Select Interpreter” → 手动指向项目下的.venv目录
uvicorn main:app --reload 启动失败的三个高频原因
错误信息常是 ImportError: cannot import name 'app' from 'main' 或 Application not found，本质都是模块导入链断裂。核心检查点：
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
-
main.py文件里必须有且仅有一个顶层变量叫app，且类型是FastAPI实例，不能是函数、类或带下划线前缀（比如_app不行） - 终端当前路径必须是
main.py所在目录，不能在子文件夹里执行uvicorn命令 - 必须已激活虚拟环境：
(.venv)出现在终端提示符最前面；Windows 激活命令是.venv\Scripts\activate，macOS/Linux 是source .venv/bin/activate；没激活就装包，uvicorn会装到全局，而 VSCode 可能用的是虚拟环境解释器，导致找不到命令
异步调试时断点不生效？检查 launch.json 的 module 字段
VSCode 默认调试配置走的是脚本模式（"program": "main.py"），但 uvicorn 是以模块方式运行的，直接 debug 会跳过 ASGI 生命周期。正确做法是用 launch.json 配置模块启动：
{
"version": "0.2.0",
"configurations": [
{
"name": "FastAPI Debug",
"type": "python",
"request": "launch",
"module": "uvicorn",
"args": [
"main:app",
"--reload",
"--host",
"127.0.0.1",
"--port",
"8000"
],
"console": "integratedTerminal",
"justMyCode": true
}
]
}
关键点："module": "uvicorn" 表示让调试器以模块方式启动，而不是执行单个文件；"args" 里传的 "main:app" 必须和文件名、变量名完全一致，大小写敏感，中间不能有空格。
真正麻烦的不是装多少东西，而是每一步的上下文是否连贯：Python 版本、PATH、终端路径、虚拟环境状态、解释器选择、uvicorn 启动参数、调试配置——其中任意一环断开，都会让 http://127.0.0.1:8000 打不开，而且错误提示往往藏在终端滚动日志里，不翻到底根本看不到。
