VSCode怎么配置FastAPI启动任务_VSCode异步Python开发设置【配置】-VSCode-PHP中文网

能直接跑通 fastapi 的最小 vscode 启动配置只需 python、python 扩展、pylance 和 uvicorn，关键在用 "module": "uvicorn" 调试模式、args 中明确指定 "main:app" 和 "--reload"、正确选择虚拟环境解释器，并确保 app 是顶层 fastapi 实例变量。

vscode怎么配置fastapi启动任务_vscode异步python开发设置【配置】

能直接跑通 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 的命令行参数，顺序和拼写错误会导致热重载不工作、端口绑定失败或找不到模块。

python学习

Python 编程学习助手 skill，面向零基础用户。当用户表达以下意图时触发： - 学习 Python 基础概念（变量、数据类型、循环、函数、类等） - 请求 Python 练习题或测验 - 请求审查或调试 Python 代码 - 请求 Python 项目实战指导（爬虫、数据分析、Web 开发等入门项目） - 泛化表述如"教我 Python""我想学编程""Python 怎么写""帮我学 Python" 此 skill

下载

必填项："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'，本质是解释器路径和包安装环境不一致。

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 不存在”。