根本原因是uvicorn的--reload依赖文件监听并fork新进程，而debugpy仅attach主进程，不接管子进程；正确做法是launch.json中设"module": "uvicorn"、"args": ["main:app", "--reload"]并启用"subprocess": true。
为什么修改代码后Uvicorn没自动重启？
默认用 uvicorn.run() 启动 FastAPI 时，即使加了 --reload 参数，VSCode 调试器也不会触发重载——因为调试模式下 Python 进程由 VSCode 的 debugpy 控制，Uvicorn 的文件监听机制被绕过。
根本原因是：Uvicorn 的 --reload 依赖 watchfiles 或 watchdog 监听文件变化并 fork 新进程，而 debugpy 只 attach 到单个主进程，不支持子进程自动接管调试。
- 别在
if __name__ == "__main__":块里直接调用uvicorn.run(..., reload=True)——这在调试会话中无效 - VSCode 的
launch.json中设"console": "integratedTerminal"并手动运行uvicorn main:app --reload是可行的，但无法打断点 - 真正能兼顾断点和重载的方式，是让 VSCode 启动 Uvicorn 的开发模式子进程，而非直接运行脚本
VSCode launch.json 正确配置 reload 的写法
关键不是改参数，而是换启动方式：不用 Python 模块入口，改用 uvicorn 命令行作为调试目标，并显式启用 reload 和端口绑定。
在项目根目录的 .vscode/launch.json 中，使用以下配置：
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
{
"version": "0.2.0",
"configurations": [
{
"name": "FastAPI (reload)",
"type": "python",
"request": "launch",
"module": "uvicorn",
"args": [
"main:app",
"--host", "127.0.0.1",
"--port", "8000",
"--reload",
"--reload-dir", "."
],
"console": "integratedTerminal",
"justMyCode": true
}
]
}
注意点：
-
"module": "uvicorn"表示以 uvicorn 包为入口，不是你自己的main.py -
"--reload-dir" "."显式指定监听根目录，避免某些 IDE 环境下忽略子目录变更 - 不要加
--debug（Uvicorn 已弃用），也不要设"stopOnEntry": true，否则首次加载就卡住 - 如果用 Poetry 或虚拟环境，确保 VSCode Python 解释器指向正确环境，否则
uvicorn命令可能找不到
常见重载失效场景与修复
即使配置正确，仍可能遇到“改了代码但没重启”，多数源于路径或依赖问题。
-
ImportError: cannot import name 'xxx' from 'yyy'类错误会导致 Uvicorn 启动失败，但 reload 进程静默退出，终端只闪一下——打开 VSCode 终端面板看完整日志 - 修改
pydantic模型或SQLModel类时，有时需保存两次才触发 reload，因某些导入链缓存了模块引用；可加--reload-exclude "*.pyc:__pycache__"减少干扰 - Windows 上若提示
WatchdogObserver is not supported on Windows，说明watchdog安装异常，执行pip install watchdog即可（watchfiles在 Windows 下有时监听不准） - 使用
fastapi.middleware.cors.CORSMiddleware等中间件时，若在main.py外部定义并 import，确保该文件也在--reload-dir范围内，否则修改中间件逻辑不会触发重启
调试时断点不生效？检查这三个地方
reload 模式下断点跳过或失效，通常不是 VSCode 问题，而是进程模型不匹配。
- 确认 launch.json 中没有同时启用
"subProcess": true和"console": "integratedTerminal"，二者冲突会导致 debugpy 无法 attach 子进程 - 避免在
main.py开头加import uvicorn; uvicorn.run(...)，这种写法会让 debugpy 调试的是你的脚本，不是 Uvicorn 主循环 - 如果用了
async def路由，断点打在await行可能跳过——这是 asyncio 调度特性，把断点往前移到函数入口更可靠
最稳妥的验证方式：启动调试后，在终端看到类似 INFO: Watching for file changes with StatReload 或 INFO: Using WatchdogReloader 日志，且修改任意 .py 文件后出现 INFO: Shutting down → INFO: Started server process 循环，才算真正生效。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
