Uvicorn+FastAPI每次重载报错且重启缓慢，求解决方法

每次保存文件都会触发如下错误，同时服务重启耗时很长。试过多个Python版本，运行示例代码仍出现相同问题，求解决。

报错日志 #

INFO:     Application startup complete.
WARNING:  WatchFiles detected changes in 'main.py'. Reloading...
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [5164]
Process SpawnProcess-1:
Traceback (most recent call last):
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\asyncio\runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\asyncio\base_events.py", line 685, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
asyncio.exceptions.CancelledError

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\multiprocessing\process.py", line 314, in _bootstrap
    self.run()
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\multiprocessing\process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "C:\Users\x\Documents\GitHub\bravissimo\.env\Lib\site-packages\uvicorn\_subprocess.py", line 78, in subprocess_started
    target(sockets=sockets)
  File "C:\Users\x\Documents\GitHub\bravissimo\.env\Lib\site-packages\uvicorn\server.py", line 65, in run
    return asyncio.run(self.serve(sockets=sockets))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\asyncio\runners.py", line 194, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "C:\Users\x\AppData\Local\Programs\Python\Python312\Lib\asyncio\runners.py", line 123, in run
    raise KeyboardInterrupt()
KeyboardInterrupt
INFO:     Started server process [14264]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

环境依赖 #

解决方法 #

• 切换热重载后端：将watchfiles降级到0.20.x版本，或者启动时指定仅监控必要目录：uvicorn main:app --reload --reload-dir ./
• 优化应用 shutdown 逻辑：检查代码中是否有未正确关闭的异步任务、数据库连接，用@app.on_event("shutdown")装饰器确保资源释放，避免shutdown阻塞
• 降级Uvicorn版本：将uvicorn从0.29.0降级到0.28.0，新版本可能与Python3.12存在兼容性冲突
• 禁用多进程重载：启动时添加--workers 1参数，强制单进程模式：uvicorn main:app --reload --workers 1
• 排除无关监控文件：用--reload-exclude排除虚拟环境、缓存目录，减少检测负载：uvicorn main:app --reload --reload-exclude=".env/**" --reload-exclude="__pycache__/**"

内容的提问来源于stack exchange，提问作者Quim Puiggalí