pip install uvicorn默认仅含基础HTTP支持，缺失websockets等关键依赖，导致WebSocket或--reload时报ImportError；推荐直接安装完整版pip install "uvicorn[standard]"。
pip install uvicorn 为什么启动时报错 missing websockets
最小安装只带基础 HTTP 支持，websockets 不在默认依赖里。开发中用 --reload 或处理 WebSocket 请求时会直接报 ImportError: No module named 'websockets'。
- 临时修复：运行
pip install websockets - 推荐做法：一开始就装完整版
pip install "uvicorn[standard]"，它自动包含websockets>=10.4、uvloop、httptools等关键依赖 - 验证是否装全：执行
python -c "import websockets, uvloop, httptools"，无报错才算齐
Windows 下用 uv 创建虚拟环境后 uvicorn 启动失败
常见原因是路径没激活或命令写错——尤其 Windows 的反斜杠和空格容易出问题。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
-
.venv\Scripts\Activate是 PowerShell 命令；CMD 下要用.venv\Scripts\activate.bat - 激活后命令行前必须出现
(.venv)，否则uvicorn调用的是全局 Python 环境 - 启动命令别漏掉冒号：
uvicorn main:app中的main:app是模块名加变量名，不是文件路径 - 如果提示
'uvicorn' is not recognized，确认uv install uvicorn已执行（uv安装比pip快，且默认进当前虚拟环境）
PyCharm 里配置 uvicorn 运行时提示 main:app not found
这不是代码问题，而是 PyCharm 没找对上下文。错误常发生在 Working directory 或 Module name 填错。
-
Module name必须填uvicorn（不是main，也不是留空） -
Parameters填main:app --reload，其中main是文件名（不含.py），app是main.py里定义的 FastAPI 实例变量名 -
Working directory必须设为main.py所在目录，不能是父级或子级 - 检查
main.py是否在项目根目录下，且没有语法错误（PyCharm 右下角有 Python 解释器状态栏，点开看是否报红）
docker compose 启动 uvicorn 报错 Address already in use
Docker 默认绑定 127.0.0.1:8000，但容器内要监听 0.0.0.0:8000，否则端口映射失败。
- 在
docker-compose.yml的command或CMD中显式加--host 0.0.0.0 --port 8000 - 不要依赖环境变量
UVICORN_HOST，Docker 容器里某些镜像版本不识别该变量 - 若用
uv run uvicorn main:app，确保uv版本 ≥ 0.4.35（2026 年主流镜像已内置），旧版uv run不透传参数给uvicorn - 多服务编排时，避免两个 service 都用
--reload—— 它会触发重复文件监听，导致OSError: [Errno 98] Address already in use
--reload 和 --workers 的互斥性：只要用了 --workers N，--reload 就自动失效，且不会报错，只会静默忽略。生产环境务必手动去掉 --reload，否则可能卡在单进程还误以为开了多 worker。 
