ModuleNotFoundError: No module named 'uvicorn'说明PyInstaller未自动打包uvicorn，需显式添加--hidden-import uvicorn或--hidden-import uvicorn.main，并确保已安装uvicorn[standard]。
ModuleNotFoundError: No module named 'uvicorn'
打包成 EXE 后运行直接报这个错，说明 uvicorn 根本没打进可执行文件里。
PyInstaller 默认不会自动扫描代码中 import uvicorn 这种动态导入（尤其当它藏在字符串里、配置文件里或条件分支中），也不会管 requirements.txt 里有没有写。
- 先确认当前环境已安装：
python -c "import uvicorn; print(uvicorn.__version__)" - 打包时显式添加：用
--hidden-import uvicorn或--hidden-import uvicorn.main - 如果用了
uvicorn[standard]，还得补上依赖项：--hidden-import uvicorn.protocols.http.h11_impl和--hidden-import uvicorn.protocols.websockets.websockets_impl - Windows 上若提示找不到 DLL，可能还要加
--add-binary手动塞入uvicorn的 C 扩展路径（常见于 conda 环境）
ERROR: Error loading ASGI app. Could not import module "backend.main"
这个错误不是 uvicorn 自身的问题，而是它尝试加载你的应用模块失败了——路径、包结构或相对导入出错了。
典型场景是项目目录结构不标准，比如 backend/main.py 里用了 from ..config import settings，但 PyInstaller 打包后工作目录变了，.. 就失效了。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 启动命令里别用点号路径：
uvicorn backend.main:app比uvicorn main:app更可靠（前提是backend是合法 Python 包，含__init__.py） - 打包前用
python -m backend.main测试能否正常导入，比直接跑main.py更贴近 EXE 行为 - 避免在
main.py开头做路径操作（如sys.path.insert(0, ...)），EXE 解压后路径是临时的，不可预测 - 如果必须动态加载模块，改用
importlib.import_module("backend.main")并捕获ImportError，比让uvicorn崩溃更可控
Unsupported upgrade request（WebSocket 连接被拒）
FastAPI + uvicorn 在 WebSocket 路由上返回 400，并带这句提示，基本锁定是 uvicorn 版本太高或太低，缺 WebSocket 协议支持。
从 uvicorn >= 0.12 开始，WebSocket 实现被拆成可选依赖，默认不装。而很多旧教程或 CI 镜像只装了裸版 uvicorn，没带 [standard]。
- 检查当前安装方式：
pip show uvicorn看Requires字段是否含websockets或wsproto - 重装指定完整版：
pip install "uvicorn[standard]"（注意引号，防止 shell 把方括号吃掉） - 验证 WebSocket 是否可用：
python -c "import uvicorn.protocols.websockets; print('ok')" - Docker 或虚拟环境里，别用
pip install uvicorn简写——它大概率漏掉协议实现
Uvicorn running on http://0.0.0.0:8000 但访问超时或 Connection refused
日志显示服务“已启动”，但浏览器打不开，问题一定在外部——不是代码没跑起来，而是网络层拦住了。
常见于容器部署、云服务器、Windows 防火墙等场景，和 uvicorn 本身关系不大，但容易误判。
- 确认监听地址没写死成
127.0.0.1：启动参数必须含--host 0.0.0.0（默认值就是它，但某些封装脚本会覆盖） - 云服务器要检查安全组规则，不只是本地防火墙；Docker 要确认
-p 8000:8000映射正确，且容器内端口和 uvicorn --port 一致 - Windows 上如果用 WSL2，
localhost可能不通，试试宿主机 IP 或host.docker.internal - 用
curl -v http://127.0.0.1:8000在服务本机测试，排除网络问题；再用netstat -ano | findstr :8000看端口是否真被 uvicorn 进程占用
ModuleNotFoundError 在 EXE 里报，和在开发环境报，根本不是一个修复路径；Unsupported upgrade request 看似是代码问题，实际是 pip 安装选项漏了一个方括号。 
