Uvicorn原生支持WebSocket但需显式安装websockets库，否则静默降级并返回400 Unsupported upgrade request；根本原因是≥0.12版本移除默认捆绑，依赖按需加载，未安装websockets时无法处理Upgrade请求。
Uvicorn 原生支持 WebSocket 协议，但必须满足依赖条件——websockets 库未安装时，uvicorn 会静默降级为不处理 WebSocket 升级请求，直接返回 400 Unsupported upgrade request。
为什么启动 FastAPI WebSocket 时出现 “Unsupported upgrade request”
这是最常见的误判点：Uvicorn 本身不自带 WebSocket 实现，而是通过插件式后端选择。新版本（≥0.12）移除了默认捆绑，改为按需加载。
-
websockets未安装 → Uvicorn 拒绝处理Upgrade: websocket请求，返回 400 - 只装了
pip install uvicorn→ 缺少websockets>=10.4，即使代码写了@app.websocket也无效 - 错误日志里通常不提示缺失依赖，只显示协议升级失败，容易误以为是路由或 CORS 问题
如何验证 WebSocket 支持已启用
不要只看 uvicorn --version，要实测依赖加载状态：
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 运行
python -c "import websockets; print(websockets.__version__)"，确保无 ImportError - 启动时加
--ws websockets显式指定后端（可选，但能快速确认是否识别） - 用
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:8000/ws手动触发握手，观察是否返回101 Switching Protocols
不同安装方式对 WebSocket 的影响
安装命令决定能力边界，不是“装了就能用”：
-
pip install uvicorn→ HTTP-only，WebSocket 路由存在但拒绝连接 -
pip install "uvicorn[standard]"→ 自动安装websockets、httptools、uvloop，生产可用 -
pip install uvicorn websockets→ 最小可行组合，适合轻量部署，但缺自动重载（watchfiles）和高性能解析器
最容易被忽略的是：Uvicorn 的 WebSocket 支持完全依赖第三方库加载时机——它在首次收到 Upgrade 请求时才尝试导入 websockets，所以即使你后续 pip install 了，也得重启服务才能生效。
