FastAPI应用通过Uvicorn运行时出现404错误的解决求助

1. 确认根路由定义是否准确 #

检查main.py中是否明确编写了根路径的路由逻辑，示例如下：

from fastapi import FastAPI

app = FastAPI()

# 必须存在该根路由定义
@app.get("/")
async def root():
    return {"message": "Hello World"}

排查时注意装饰器路径是否有拼写错误、多余空格，或是漏写了/路径的路由。

2. 验证应用实例与启动命令的匹配性 #

确保启动命令uvicorn main:app中的app，与main.py里的FastAPI实例名称完全一致：

# 实例名为app，对应命令uvicorn main:app
app = FastAPI()

# 若实例名为api，则命令需改为uvicorn main:api
# api = FastAPI()

3. 排查路由前缀或中间件干扰 #

如果应用设置了根路径前缀，比如：

app = FastAPI(root_path="/api")

则需访问http://localhost:8000/api而非根路径/。另外可暂时注释掉自定义中间件，测试是否是中间件修改请求路径导致的匹配失败。

4. 确认运行目录与文件路径匹配 #

确保在main.py所在的目录下执行启动命令。若main.py在子文件夹（如app目录）中，需调整命令为uvicorn app.main:app。

5. 通过自动文档验证路由注册情况 #

启动应用后，访问http://localhost:8000/docs或http://localhost:8000/redoc，查看已注册的路由列表。若根路径/未出现在列表中，说明路由未正确注册。

6. 检查跨文件路由的导入挂载 #

若路由分散在其他文件中，确认已将子路由正确挂载到主应用实例：

# main.py
from fastapi import FastAPI
from routes import items

app = FastAPI()
# 必须执行挂载操作
app.include_router(items.router)

此时需保证根路由要么在主应用实例中定义，要么在挂载的子路由中存在/路径的路由。

内容的提问来源于stack exchange，提问作者Andrew Chibwesha