FastAPI 调试必须用 "module": "uvicorn" 模式并配置 "args": ["main:app", "--reload", "--host", "127.0.0.1", "--port", "8000"]，禁用 "program": "main.py"；需使用最新 ms-python.python 扩展和 debugpy，正确选择虚拟环境解释器。
launch.json 配置错，断点就永远不触发——FastAPI 是靠 uvicorn 启动的异步 ASGI 应用，不是普通 Python 脚本，直接用 "program": "main.py" 模式调试，async 函数里的断点基本失效。
必须用 module 模式启动 uvicorn
VSCode 默认的 Python 调试配置走的是脚本执行路径（program），但 FastAPI 的生命周期、事件循环、依赖注入全由 uvicorn 管理。绕过它等于丢掉整个异步上下文。
-
"module": "uvicorn"是唯一能正确加载 ASGI 生命周期的方式 -
"args"必须显式包含入口模块标识，比如["main:app", "--host", "127.0.0.1", "--port", "8000"]；漏掉main:app就等于没告诉 uvicorn 去哪找应用 - 不要写
"program": "main.py"—— 即使文件存在，也会跳过uvicorn.run()流程，Depends注入、中间件、异常处理器全不生效
async 函数里断点不进？先看扩展和调试器版本
旧版 Python 扩展（尤其是还在用 ptvsd 的）对协程栈帧支持极差，常见现象是断点停在 await 行但进不去后续逻辑，或者直接跳过整段 async def。
- 确保安装的是最新 Microsoft 官方
ms-python.python扩展（2026 年已强制使用debugpy） - 检查
debugpy是否启用：打开命令面板（Ctrl+Shift+P），搜Python: Select Interpreter，确认解释器路径下有debugpy（可通过pip show debugpy验证） - 避免在
async def第一行打断点——某些 Python 3.9/3.10 + debugpy 组合下首行断点会静默失效；移到第二行或函数体内部更稳
--reload 热重载要手动加进 args，别靠终端补救
调试时如果一边跑 VSCode 的 launch 配置，一边又在终端敲 uvicorn main:app --reload，两个进程会抢端口，后者失败，前者因没配 --reload 根本不响应代码变更。
-
"args"中必须显式加入"--reload"，且位置要在main:app之后，例如：["main:app", "--reload", "--host", "127.0.0.1", "--port", "8000"] - Linux/WSL 下若提示
WatchFiles not available，补装watchfiles：pip install watchfiles（uvicorn[standard]不自动带它） - Windows/macOS 通常开箱即用，但注意：
--reload仅监控 Python 文件，默认不监听.env或pyproject.toml变更
虚拟环境和依赖管理容易被忽略的细节
VSCode 的 Python 扩展不会自动识别项目根目录下的 .venv 或 venv，更不会管 Poetry 环境，选错解释器会导致类型提示错乱、import 报红、甚至调试时找不到模块。
- 务必通过命令面板运行
Python: Select Interpreter，手动指向你项目用的虚拟环境（如.venv/bin/python或.venv/Scripts/python.exe） - 如果用
poetry，优先执行poetry shell激活后再开 VSCode（或用code .在已激活环境中执行），否则Python: Select Interpreter可能找不到poetry创建的环境路径 -
requirements.txt或pyproject.toml里必须明确包含uvicorn[standard]，否则--reload和 WebSocket 支持可能缺失
uvicorn 全权接管启动流程——任何试图“绕过它”的捷径，最后都会卡在断点不命中、依赖不注入、热重载失灵这些地方。 
