能直接跑通 FastAPI 的最小 VSCode 配置只需 Python（安装时勾选 Add to PATH）、Python 扩展、Pylance 和 uvicorn；最常失败原因是终端未激活虚拟环境或 uvicorn 找不到 main.py 中的 app 变量。

能直接跑通 FastAPI 的最小 VSCode 配置，只用装 Python、Python 扩展、Pylance 和 uvicorn，其他都可延后。最常卡住的不是代码，而是终端没激活虚拟环境或 uvicorn 命令找不到 app 变量名。

为什么 async 路由函数不提示 await / 返回值补全

Pylance 默认不深度推导异步函数签名，尤其当返回类型没显式标注时，会退化成同步函数提示。

• 在 .vscode/settings.json 中启用类型检查："python.analysis.typeCheckingMode": "basic"
• 每个 async def 路由必须写明返回类型，比如 async def read_item() -> dict:，不能留空或只写 def
• Pydantic 字段若用 str | None 写法，Pylance 在异步上下文中可能跳过字段推导；改用 Optional[str]
• 避免在 async def 里混用 yield——FastAPI 不支持原生异步生成器响应，会直接中断补全链

launch.json 配置错，断点就永远不触发

FastAPI 是 ASGI 应用，生命周期由 uvicorn 管理。"program": "main.py" 模式会绕过整个异步上下文，Depends、中间件、异常处理器全不生效。

python 查询技能

查询客流数据，输出JSON格式，可直接导入Bitable等可视化工具

下载

• 必须用 "module": "uvicorn"，不能用 "program"
• "args" 必须包含入口标识，例如 ["main:app", "--reload", "--host", "127.0.0.1", "--port", "8000"]；漏掉 main:app 就等于没告诉 uvicorn 去哪找应用
• "console": "integratedTerminal" 必须设上，否则看不到日志和重载提示
• 调试 async 函数时，别在第一行打断点——某些 Python 3.9/3.10 + debugpy 组合下会静默失效；移到第二行或函数体内部更稳

Pydantic 模型字段在 VSCode 里不补全

Pylance 依赖静态分析，而 Pydantic 的 __init__ 和 __setattr__ 是动态实现的，字段推导容易失效。

• 确保 pydantic 版本 ≥ 2.6，并更新 pyright 插件（Pylance 内置）
• 模型定义上方加 # pyright: reportGeneralTypeIssues=false 是临时绕过方案，不推荐长期用
• 避免用 Field(default_factory=lambda: ...) 这类运行时构造逻辑；优先用字面量默认值或 default=None + 类型标注
• item.model_dump() 能提示，但 item.name 不提示？说明 Pylance 没识别出 item 是 BaseModel 实例——检查变量是否被赋值前就用了，或是否在条件分支里未覆盖所有路径

真正容易被忽略的是：VSCode 不会自动识别项目根目录下的 .venv 或 venv 文件夹，也不会管 Poetry 环境。选错解释器，类型提示、补全、调试全崩，但错误往往不报在表面，而是静默降级为“没提示”或“断点灰掉”。