根本原因是uvicorn启动方式与调试器模式不匹配:必须用"module": "uvicorn"并指定args为["main:app", "--host", "127.0.0.1", "--port", "8000"],禁用"program"直运行;justMyCode需设为false以调试依赖注入和中间件;启用subProcess:true支持--reload热重载断点持续生效。

VSCode 调试 FastAPI 时断点不触发、类型提示不准确,根本原因不是插件没装全,而是 uvicorn 启动方式和调试器模式不匹配。
launch.json 必须用 module 模式启动 uvicorn,不能用 program
FastAPI 是异步框架,依赖 uvicorn 的 ASGI 生命周期管理上下文。如果在 launch.json 中写 "program": "main.py",VSCode 会直接执行脚本,绕过 uvicorn 的事件循环初始化,导致:
- async/await 语句无法被正确挂起,断点设了也跳过
- 依赖注入(如
Depends)失效,request.state等对象为None - 中间件(如
CORSMiddleware)不生效,请求甚至进不到路由层
正确配置必须使用 "module": "uvicorn",并确保 args 第一项是模块路径加实例名,例如 "app.main:app" 或 "main:app" —— 漏掉 :app 就等于没指定入口。
justMyCode 设为 false 才能调试中间件和依赖注入逻辑
FastAPI 的核心行为(比如参数解析、依赖注入、异常处理器)都发生在 uvicorn 和 fastapi 包内部。默认 justMyCode: true 会让 debugpy 自动跳过所有第三方代码,结果就是断点只停在你的路由函数第一行,进不去 Depends 里的函数,也看不到 Request 对象怎么被构造的。
改成 false 后,你可以:
- 在
def get_user(db: Session = Depends(get_db)):这行设断点,一路跟进到get_db函数体 - 在中间件中打断点,观察
request.headers实际值 - 查看
fastapi.dependencies.utils.solve_dependencies内部调用栈
副作用是调试器偶尔会停在 uvicorn 的底层 event loop 里,按 F5 继续即可,不影响主线逻辑跟踪。
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期,并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看,该技能
subProcess: true 是热重载(--reload)下保持断点有效的关键
开发时加 --reload 很方便,但 uvicorn 默认用 fork 或 spawn 启新进程,旧调试会话会丢失上下文,导致改完代码保存后断点全部失效,必须重启调试器。
加上 "subProcess": true 后,debugpy 会主动 attach 到子进程,让断点在重载后依然有效。这个字段只在 type: "debugpy" 配置下起作用,type: "python" 不支持。
注意:如果项目结构是 app/main.py,还要配 "cwd": "${workspaceFolder}/app",否则 --reload 会监听错目录,改 routers/ 下的文件不触发重载。
Pylance 类型提示不准?检查 __init__.py 和模块导入路径
FastAPI 大量依赖类型提示做自动校验和文档生成,但 VSCode 的 Pylance 常报 Cannot resolve symbol "app" 或参数类型显示为 Any,问题往往不在配置,而在 Python 模块系统本身:
- 确保
app/目录下有空的__init__.py文件,否则from app.main import app可能失败 - 避免在
main.py里用相对导入(如from .routers import items)却没把项目根目录设为 source root;建议统一用绝对导入:from app.routers.items import router - 如果用了
pyproject.toml,确认[tool.black]或[tool.ruff]没禁用类型检查相关规则
改完后,在 VSCode 里右键 → “Reload Window”,Pylance 会重新索引,类型提示通常立刻恢复准确。
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!










