Uvicorn运行报Error loading ASGI app无法导入src.main问题求助

安全阿岳

2026-10-1

"Error loading ASGI app. Could not import module 'src.main'" 报错解决方案

按以下顺序逐一排查：

确认src/main.py中存在正确的FastAPI实例声明，示例代码如下：
```
from fastapi import FastAPI
# 此处实例名必须和启动命令中冒号后的名称一致
app = FastAPI()
```
如果你定义的实例名不是app（比如是api），需要同步修改启动命令对应字段，例如改为uvicorn src.main:api --reload。
检查Python模块搜索路径配置，默认情况下Python不会自动将当前工作目录加入搜索路径，需要手动指定：
如果你在项目根目录（即src、venv文件夹所在的上层目录）启动，执行对应系统的命令：
- Linux/macOS 终端：
```
PYTHONPATH=. uvicorn src.main:app --reload
```
- Windows CMD：
```
set PYTHONPATH=. && uvicorn src.main:app --reload
```
- Windows PowerShell：
```
$env:PYTHONPATH="."; uvicorn src.main:app --reload
```
如果你已经进入src目录启动，执行对应命令：
- Linux/macOS 终端：
```
PYTHONPATH=. uvicorn main:app --reload
```
- Windows CMD：
```
set PYTHONPATH=. && uvicorn main:app --reload
```
- Windows PowerShell：
```
$env:PYTHONPATH="."; uvicorn main:app --reload
```
排查main.py内部导入错误：单独执行python src/main.py（根目录下执行）或者python main.py（src目录下执行），如果运行直接报错，说明是文件内部的导入逻辑有问题：
- 如果用了绝对导入（例如from src.database import get_db），必须在项目根目录下启动，且配置好PYTHONPATH
- 如果用了相对导入（例如from .database import get_db），不能直接运行python main.py，只能用uvicorn启动
排查基础拼写/大小写问题：确认main.py文件名没有拼写错误，Linux/macOS系统区分大小写，注意不要写成Main.py、mian.py这类错误名称，同时确认src目录下的__init__.py文件存在且无语法错误。
确认uvicorn调用路径正确：执行which uvicorn（Linux/macOS）或where uvicorn（Windows）查看uvicorn的安装路径，虚拟环境下路径应指向venv/bin/uvicorn（Linux/macOS）或venv\Scripts\uvicorn.exe（Windows），避免调用到全局安装的uvicorn。

内容的提问来源于stack exchange，提问作者Bilal Haroon