凌晨一点我在测试环境把一套 FastAPI 服务拆成主应用加子应用主应用挂在 /api子应用挂在 /api/admin。部署完打开 /api/docs 一切正常打开 /api/admin/docs 页面也能渲染但 Swagger UI 里接口请求地址还死死指向 /admin点一次 404 一次。更诡异的是把子应用 root_path 改成 /api/admin 之后外部访问正常了内网直连 8000 端口访问 /admin/docs 却又错。那一个晚上我把 root_path 的所有排列组合都试了一遍才彻底搞明白这个看似简单的参数到底在改什么。这篇文章不聊高深理论就把它当成一次踩坑实录。我会先用一个最小示例复现问题再解释 root_path 在 FastAPI 和 Starlette 里那两套容易打架的运行逻辑最后给几种可以直接落地的配置方案和验证方法。看完你至少能少熬一个夜。1. 挂在 /admin 下的子应用为什么 OpenAPI 还写着 /admin1.1 最小复现主应用挂载子应用先上一个最简单的项目结构两个 FastAPI 实例一个主应用挂载一个子应用# admin.py from fastapi import FastAPI