结论：uvicorn“装了却找不到”本质是环境错配。常见原因包括虚拟环境未激活、Python/pip版本不一致、IDE解释器配置错误；命令行uvicorn不可用因PATH未包含Scripts/bin目录；PyInstaller需--hidden-import显式打包；APP路径错误则需检查工作目录、PYTHONPATH和__init__.py。
直接说结论：不是没装上，而是 uvicorn 没装进当前 Python 解释器能看见的环境里。90% 的情况是虚拟环境没激活、Python 和 pip 版本不一致、或安装了但解释器路径错了。
pip install 成功但 import uvicorn 报错
这种“明明装了却找不到”的现象，本质是 pip 安装到了 A 环境，而你运行 Python 的是 B 环境。常见触发点：
- 用
python3 -m venv myenv创建了虚拟环境，但没执行source myenv/bin/activate（macOS/Linux）或myenv\Scripts\activate（Windows）就直接 pip install - 系统有多个 Python 版本（比如
python指向 3.9，python3.11是另一个），而你用pip3.11 install uvicorn装的，却用python启动脚本 - PyCharm 或 VS Code 没选对解释器——界面右下角显示的 Python 路径，和终端里
which python输出的不一致
验证方式很简单：在报错的环境下运行 python -c "import sys; print('\n'.join(sys.path))"，再运行 python -m pip show uvicorn，看输出的 Location 是否在上面的 sys.path 列表中。
uvicorn: command not found（命令行无法调用）
这个错误和 import 失败不是一回事：import uvicorn 是 Python 解释器行为，而 uvicorn --help 是 shell 在 PATH 里找可执行文件。关键区别在于：
-
pip install uvicorn会把uvicorn可执行脚本放在site-packages同级的Scripts/（Windows）或bin/（macOS/Linux）目录下 - 该目录必须在系统 PATH 中，shell 才能识别命令；虚拟环境激活时，PATH 会自动 prepend 这个路径，未激活则不会
- 如果用
pip install --user uvicorn，脚本会装到用户级目录（如~/.local/bin），需手动加进 PATH
快速修复：先确认是否在虚拟环境中，再检查 which uvicorn（macOS/Linux）或 where uvicorn（Windows）。返回空说明 PATH 里真没有——要么激活环境，要么补 PATH，别硬改命令。
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
打包成 EXE 后 ModuleNotFoundError: No module named 'uvicorn'
PyInstaller 默认不自动收集 uvicorn 的入口模块（尤其是它依赖的 uvicorn.main 和 uvicorn.config），即使你代码里写了 import uvicorn，也可能漏掉子模块。
- 最稳妥做法是显式告诉 PyInstaller 包含整个包：
pyinstaller --hidden-import=uvicorn --hidden-import=uvicorn.main --hidden-import=uvicorn.config your_script.py - 如果项目结构是
src/main.py且启动逻辑在代码里（比如uvicorn.run("main:app", ...)），还要加--add-data把src目录带上，否则模块路径解析失败 - 避免用
subprocess.run(["uvicorn", ...])方式调用——EXE 里没有独立的uvicorn命令，得走 Python 内部 API
注意：不要指望 --onefile 自动解决所有依赖，uvicorn 的 ASGI 加载机制涉及动态 import，必须靠 --hidden-import 显式声明。
APP 参数路径报 ModuleNotFoundError（如 uvicorn api.main:app）
这个错误不是缺模块，是 uvicorn 找不到你写的那个 api.main 模块。根本原因永远是当前工作目录或 PYTHONPATH 不匹配。
- 运行命令前，确保你在项目根目录（即
api/目录的父目录），而不是api/里面 - 如果项目结构是
src/api/main.py，但你想用uvicorn api.main:app，就必须加--app-dir src或提前设置PYTHONPATH=src - 检查
api/__init__.py是否存在——虽然 Python 3.7+ 允许隐式命名空间包，但 uvicorn 的 importer 默认按传统包逻辑加载，没__init__.py容易出问题 - 别用相对路径写法，比如
uvicorn ./api/main:app或uvicorn ../api/main:app，uvicorn 不支持这种语法
最省事的调试方式：先在 Python 里手动导入试试，python -c "from api.main import app; print(app)"，能过才说明路径没问题。
