Uvicorn启动成功但无法访问,主因是请求未进入服务:端口被占、绑定地址错误(如未用0.0.0.0)、WSL2/防火墙拦截、前端地址与实际端口不匹配,或IDE调试残留进程导致静默失败。

Uvicorn 启动成功但无法访问,八成不是代码没跑起来,而是请求根本没进到服务里——端口、绑定地址、网络栈或前端配置错了一处,浏览器就收不到响应。
为什么 uvicorn 显示 running on http://0.0.0.0:8000 却打不开?
这是最典型的“假启动”现象:进程在跑,日志有输出,但你本地 curl 或浏览器连不上。关键看两点:
-
0.0.0.0表示监听所有网卡,但 Windows/macOS 上某些防火墙或 WSL2 会拦截该绑定;换成--host 127.0.0.1更可靠 - 检查实际监听状态:
lsof -i :8000(macOS/Linux)或Get-NetTCPConnection -LocalPort 8000(PowerShell),确认输出里有LISTEN且OwningProcess是你的 uvicorn PID - 如果用的是 WSL2,Windows 主机上
netstat查不到监听,但 WSL 内部lsof -i :8000能看到 —— 此时需关掉 WSL2 或加--host 127.0.0.1 --port 8000
前端连的后端地址和 uvicorn 实际监听端口不一致
常见于 Screenshot-to-Code、Gradio 封装类项目:后端 uvicorn 跑在 :7001,但前端代码写死请求 http://localhost:8000/api/...,自然 404 或 connection refused。
- 先确认 uvicorn 真实端口:
uvicorn main:app --port 7001中的7001,不是默认值 - 再查前端配置文件(如
.env、config.js或api.ts),把BASE_URL或API_HOST改成匹配的http://localhost:7001 - 改完务必硬刷新浏览器(Ctrl+Shift+R),避免缓存旧的请求地址
PyCharm/VS Code 调试中断后 uvicorn 还在后台跑
点红色停止按钮 ≠ 进程退出。uvicorn --reload 模式会 fork 子进程,IDE 只杀主进程,子进程继续占着端口,导致下次启动报 Address already in use。
Uvicorn 0.52.1 是 Python ASGI Web 服务器,提供异步应用服务及 WebSocket 支持,常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理所需依赖。
- 别信任务管理器里有没有
uvicorn字样 —— 它常显示为python.exe - Windows 上用管理员 PowerShell 执行:
Get-NetTCPConnection -LocalPort 8000 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force } - macOS/Linux 直接:
lsof -ti:8000 | xargs kill -9 - 懒人法:启动时加
--port 8001绕开,但仅限临时验证,别跳过查根因
ModuleNotFoundError 或 AttributeError 导致服务静默失败
日志里没报错,但 curl http://127.0.0.1:8000 返回空或 connection refused —— 很可能 uvicorn 根本没加载出应用对象,提前退出了,而 IDE 或终端没显式打出错误。
- 手动执行加载测试:
python -c "from main import app; print(app)",看是否抛ModuleNotFoundError或AttributeError: 'module' object has no attribute 'app' - 确认
main.py里定义的是app = FastAPI(),不是application、fastapi_app或缩写成a - 工作目录必须是
main.py所在目录,否则uvicorn main:app会找不到模块 —— PyCharm 里检查 Run Configuration 的Working directory - 缺
__init__.py时路径写法要变:uvicorn api.main:app错,得写uvicorn api/main:app
真正难排查的从来不是“报什么错”,而是“没报错却连不上”——这时候得一层层验:端口真在监听吗?请求地址真发到这个端口了吗?应用对象真被 import 出来了吗?少跳一步,就卡半天。










