uvicorn 进程残留问题

tags:

• fastapi
• python
• windows
• troubleshooting
• uvicorn

商店版 Python 导致 uvicorn 进程残留问题分析

一、问题现象

在使用 Windows 商店版 Python（Microsoft Store 安装）开发 FastAPI 项目时，出现以下问题：

二、根本原因分析

2.1 商店版 Python 的特殊性

Windows 商店版 Python（MSIX 打包）与普通官方 Python 有本质区别：

2.2 uvicorn --reload 的进程模型

uvicorn --reload启动后会创建一个主进程（Reloader），由它派生**子进程（Server）**来运行 FastAPI 应用：

主进程（Reloader） 子进程（Server） ┌──────────────────┐ 启动 ┌──────────────────┐ │ 监控文件变化 │ ──────────────→ │ 运行 FastAPI 应用 │ │ 管理子进程生命周期 │ │ 处理 HTTP 请求 │ └──────────────────┘ └──────────────────┘

2.3 问题链条

三、验证方法

3.1 检查 Python 来源

# 查看 Python 安装路径where.exe python# 检查虚拟环境指向typevenv\pyvenv.cfg

[!warning] 商店版 Python 的特征

• 路径包含WindowsApps
• pyvenv.cfg中的home指向C:\Program Files\WindowsApps\...

3.2 检查进程残留

# 查看端口占用netstat-ano|findstr 8000# 查看 Python 进程tasklist|findstr python

3.3 检查 Ctrl+C 是否有效

uvicorn main:app--reload# 按 Ctrl+C# 无效 → 商店版 Python ⚠️（问题存在）# 有效 → 官方 Python ✅（问题已解决）

四、解决方案

4.1 根本解决：卸载商店版，安装官方版

步骤 1：卸载商店版 Python

[!note] 两种方式可选：优先使用方式一（系统设置卸载）；若卸载后python命令仍指向商店版，再用方式二（手动清理别名）。

方式一：通过系统设置卸载

1. 按 Win + I 打开设置
2. 左侧选择系统 → 右侧点击系统组件（或直接搜索"应用执行别名"）
3. 找到应用执行别名入口，点击进入
4. 在列表中找到 python.exe 和 python3.exe（应用安装程序），关闭这两个开关

方式二：手动删除商店版 Python 别名

1. 关闭所有终端窗口（含 VS Code 终端、PowerShell、PyCharm 等）
2. 按Win + R，输入powershell，按Ctrl + Shift + Enter以管理员身份打开
3. 执行以下命令（先终止进程再删除文件）：

# 终止所有 Python 进程Stop-Process-Name python*-Force-ErrorAction SilentlyContinue# 删除商店版 Python 的执行别名$files= @("$env:LOCALAPPDATA\Microsoft\WindowsApps\python.exe","$env:LOCALAPPDATA\Microsoft\WindowsApps\python3.exe","$env:LOCALAPPDATA\Microsoft\WindowsApps\python3.13.exe","$env:LOCALAPPDATA\Microsoft\WindowsApps\pythonw.exe","$env:LOCALAPPDATA\Microsoft\WindowsApps\pythonw3.exe","$env:LOCALAPPDATA\Microsoft\WindowsApps\pythonw3.13.exe")foreach($fin$files){if(Test-Path$f){Remove-Item$f-ForceWrite-Host"已删除:$f"}}

步骤 2：安装官方 Python

# 访问 https://www.python.org/downloads/ 下载安装包# 安装时务必勾选 "Add Python to PATH"# 验证安装python--version python-c"import sys; print(sys.executable)"# 应显示：C:\Users\{用户名}\AppData\Local\Programs\Python\Python313\python.exe

步骤 3：重建虚拟环境

# 删除旧虚拟环境rmdir/s venv# 确认使用官方 Pythonwhere.exe python# 创建新虚拟环境python-m venv venv# 验证虚拟环境配置typevenv\pyvenv.cfg# home 应指向官方 Python 路径，而非 WindowsApps# 激活并安装依赖venv\Scripts\activate pip install-r requirements.txt

4.2 临时方案（不重装 Python）

[!tip] 如果暂时无法重装，可使用以下两种临时绕过方式

方法 1：不使用--reload

uvicorn main:app# 修改代码后手动重启

方法 2：更换 reload 引擎

uvicorn main:app--reload--reload-engine watchfiles

4.3 清理已残留的进程

# 查找占用 8000 端口的进程netstat-ano|findstr 8000# 按 PID 逐个终止（替换为实际 PID）taskkill/F/PID 18732 taskkill/F/PID 16424# 检查是否清理干净netstat-ano|findstr 8000

五、问题验证

5.1 虚拟环境提示符颜色

5.2 成功迁移的标志

# 1. where.exe python 显示 venv 在第 1 位D:\project\venv\Scripts\python.exe ← 第1位 ✅ C:\Users\...\Python313\python.exe ← 第2位# 2. pyvenv.cfg 中 home 指向官方 Pythonhome = C:\Users\{用户名}\AppData\Local\Programs\Python\Python313# 3. Ctrl+C 可以正常退出uvicorn main:app--reload# 按 Ctrl+C → 服务正常退出 ✅# 4. 端口不再残留netstat-ano|findstr 8000# 无输出 ✅

六、经验总结

6.1 根本原因

[!danger] 根本原因
Windows 商店版 Python（MSIX 打包）的沙箱/应用执行别名机制导致信号处理异常，使得uvicorn --reload派生的子进程无法被正常终止，从而产生python.exe进程残留和8000端口占用。

6.2 核心教训

1. ❌不要使用 Windows 商店版 Python 进行开发
   └── 沙箱机制导致信号处理异常，Ctrl+C无效

2. ✅使用官方 Python 安装包
   └── 正常的进程管理和信号处理

3. ✅定期检查 Python 来源
   └──where.exe python确认不在WindowsApps下

4. ✅绿色(venv)才是健康状态
   └── 提示符颜色是快速判断虚拟环境状态的指标

6.3 快速检查清单

• where.exe python→ 第1位是venv/Scripts/python.exe
• pyvenv.cfg→home指向官方 Python 路径（非WindowsApps）
• python -c "import sys; print(sys.executable)"→ 显示 venv 路径
• 虚拟环境提示符是绿色(venv)
• uvicorn main:app --reload→Ctrl+C能正常退出
• netstat -ano | findstr 8000→ 无进程占用

七、参考资料

• Python 官方下载
• Uvicorn 文档 - Reload
• Windows MSIX 打包说明