FastAPI/uvicorn（或hypercorn）中root-path为何未按预期生效？

你搞反了root_path的作用——它不是用来给路由加前缀的，而是给反向代理场景设计的。

问题本质 #

当你用uvicorn main:app --root-path /api/v1启动时，FastAPI会认为自己被部署在反向代理的/api/v1路径之后，它的作用是让应用生成的文档、重定向等链接自动带上这个路径，不会改变路由的匹配规则。

你的预期是让所有路由挂载在/api/v1下（比如/app变成/api/v1/app），这时候应该用路由前缀，而非root_path。

正确实现方式 #

方式1：FastAPI初始化时指定prefix（FastAPI 0.73.0+支持）

from fastapi import FastAPI, Request

# 直接给整个应用加前缀
app = FastAPI(prefix="/api/v1")

@app.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "prefix": "/api/v1"}

方式2：用APIRouter挂载前缀（更灵活，适合模块化开发）

from fastapi import FastAPI, APIRouter, Request

# 创建路由实例并指定前缀
router = APIRouter(prefix="/api/v1")

@router.get("/app")
def read_main(request: Request):
    return {"message": "Hello World", "prefix": "/api/v1"}

# 将路由注册到应用
app = FastAPI()
app.include_router(router)

启动后访问http://127.0.0.1:8000/api/v1/app就能得到预期响应。

为什么你现在的情况和预期相反？ #

当你设置root_path="/api/v1"后，FastAPI内部会认为所有请求的/api/v1前缀会被反向代理去掉，所以它只会匹配去掉前缀后的路径：

• 若反向代理把/api/v1/app转发给/app，FastAPI才能匹配到你的路由
• 你直接访问http://127.0.0.1:8000/api/v1时，FastAPI会尝试匹配/路径（自动去掉root_path前缀），但你的代码里没有/路由，所以返回404
• 你访问http://127.0.0.1:8000/时能得到响应，大概率是代码里的路由实际为/而非/app（可能是描述或代码书写失误），但核心逻辑是root_path不影响路由匹配，仅适配代理场景。

版本适配 #

你使用的FastAPI 0.85.1已经支持prefix参数，直接用这个方式就能实现路由前缀需求。

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