能直接跑通 FastAPI 的最小 VSCode 启动配置只需 Python、Python 扩展、Pylance 和 uvicorn，关键在用 "module": "uvicorn" 调试模式、args 中明确指定 "main:app" 和 "--reload"、正确选择虚拟环境解释器，并确保 app 是顶层 FastAPI 实例变量。
能直接跑通 FastAPI 的最小 VSCode 启动配置，只依赖 python、uvicorn 和正确的 launch.json；绝大多数启动失败不是代码问题，而是调试模式选错、app 变量名不匹配，或终端没激活虚拟环境。
为什么 program 模式启动 FastAPI 会失效
FastAPI 是 ASGI 应用，生命周期由 uvicorn 管理，不是普通脚本。用 "program": "main.py" 会绕过 uvicorn.run()，导致 async 函数断点不触发、Depends 不执行、中间件不加载。
- 必须用
"module": "uvicorn"，这是唯一支持 ASGI 异步上下文的调试模式 -
"args"必须显式传入入口标识，例如["main:app", "--reload"]，漏掉main:app就等于没告诉 uvicorn 去哪找应用 - 旧版 Python 扩展（仍用 ptvsd）对协程调试支持差，务必确认已升级到最新
ms-python.python并启用debugpy
launch.json 中 args 参数怎么写才生效
args 是调试器真正传递给 uvicorn 的命令行参数，顺序和拼写错误会导致热重载不工作、端口绑定失败或找不到模块。
- 必填项：
"main:app"（模块名 + 变量名，不含.py），且app必须是顶层变量、类型为FastAPI实例 - --reload 必须显式加入：
"--reload"，否则改代码不会自动重启；位置应在main:app之后 - 如需自定义 host/port，加在后面即可：
["main:app", "--reload", "--host", "127.0.0.1", "--port", "8000"] - Linux/WSL 下若提示
WatchFiles not available，补装watchfiles：pip install watchfiles
终端能跑 uvicorn main:app --reload，但 VSCode 调试启动不了
常见现象是调试控制台卡在 “Starting debugpy” 或直接报 ModuleNotFoundError: No module named 'uvicorn'，本质是解释器路径和包安装环境不一致。
立即学习“Python免费学习笔记（深入）”；
- VSCode 必须手动指定项目虚拟环境的 Python 解释器：按
Ctrl+Shift+P→Python: Select Interpreter→ 选中.venv/bin/python（macOS/Linux）或.venv\Scripts\python.exe（Windows） - 确保
uvicorn已装在该虚拟环境中：pip list | grep uvicorn，不能只靠全局 pip 安装 - 如果用
fastapi[all]，它会自动装uvicorn[standard]（含uvloop和httptools），比单独pip install uvicorn性能更好 - 检查右下角状态栏是否显示正确解释器路径；没变就关掉终端再重开一个
启动后访问 http://127.0.0.1:8000/docs 报 404 或空白页
不是前端问题，而是 FastAPI 实例未正确挂载静态资源或路由未注册——通常因 app 变量被意外覆盖、重命名，或 main.py 里有语法错误导致模块导入失败。
- 确认
main.py顶层只有且仅有一个app = FastAPI()，不要写成_app、my_app或App()类实例 - 终端当前路径必须是
main.py所在目录，不能在子文件夹里执行 uvicorn 命令 - 如果用子模块结构（如
src/main.py），启动命令要写成src.main:app，而非main:app - 检查终端提示是否有
INFO: Application shutdown—— 如果刚启动就退出，说明main.py有未捕获异常，比如ImportError或拼写错误
最易被忽略的一点：VSCode 调试器不会自动激活虚拟环境，即使你在终端里手动 source .venv/bin/activate 也没用；它只认 launch.json 里 "module" 指向的解释器路径，以及该路径下是否真有 uvicorn 可执行模块。任何环节断链，都会表现为“命令找不到”或“app 不存在”。
