FastAPI搭配WatchFiles遇问题：重载卡顿及端口冲突

问题现象 #

1. 保存代码（Ctrl+S）后，WatchFiles偶尔卡在重载状态，终端完全卡顿无法操作，只能强制关闭。
2. 强制关闭终端后，用原端口启动应用会运行旧代码，必须换端口才能加载新版本。
3. 通过netstat能查到端口被占用，但Windows任务管理器找不到对应PID，无法直接释放端口。

复现步骤 #

• 在FastAPI项目中修改代码并按Ctrl+S保存
• 观察到WatchFiles进入重载状态后卡住，终端无响应

预期与实际行为 #

• 预期：应用正常重载，终端保持响应
• 实际：WatchFiles重载卡顿，终端无响应，需强制关闭终端

代码示例 #

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

解决方案 #

一、解决WatchFiles重载卡顿问题 #

1. 升级FastAPI及依赖版本
   FastAPI 0.0.4是非常老旧的版本，存在大量未修复的兼容性问题。直接升级到稳定版：

   pip install --upgrade fastapi uvicorn
   

   新版本的FastAPI与WatchFiles兼容性更好，能避免大部分重载卡顿问题。

2. 优化WatchFiles监听范围
   避免监听不必要的文件/目录（如缓存文件、虚拟环境），减少触发重载的频率。启动时添加排除参数：

   uvicorn main:app --reload --reload-exclude "__pycache__/*" --reload-exclude "*.pyc" --reload-exclude "venv/*"
   

3. 切换重载引擎
   若升级后仍有问题，可尝试切换到watchgod作为重载引擎：
   先安装依赖：

   pip install watchgod
   

   再用以下命令启动：

   uvicorn main:app --reload --reload-engine watchgod
   

二、解决端口无法释放问题 #

1. 精准杀死占用端口的进程
   打开命令提示符（CMD）或PowerShell，执行以下步骤：

   • 查找端口对应的PID：

     # CMD命令
     netstat -ano | findstr :<你的端口号>
     # PowerShell命令
     Get-NetTCPConnection -LocalPort <你的端口号> | Select-Object LocalPort, OwningProcess
     

   • 强制杀死该进程：

     # CMD命令
     taskkill /F /PID <查到的PID>
     # PowerShell命令
     Stop-Process -Id <查到的PID> -Force
     

2. 批量杀死所有Python进程（紧急情况）
   如果找不到具体PID，可直接杀死所有Python进程：

   # CMD命令
   taskkill /F /IM python.exe
   taskkill /F /IM pythonw.exe
   

3. 关闭Windows快速启动
   快速启动可能导致进程残留占用端口，关闭方法：

   • 打开「控制面板」→「电源选项」→「选择电源按钮的功能」
   • 点击「更改当前不可用的设置」
   • 取消勾选「启用快速启动」，重启电脑

内容的提问来源于stack exchange，提问作者Pratik Kharche