FastAPI的root_path配置避坑指南：为什么你的API在Docker里访问总是404？

FastAPI的root_path配置避坑指南：为什么你的API在Docker里访问总是404？

当你第一次将FastAPI应用部署到Docker容器时，那种兴奋感可能很快会被"404 Not Found"的红色错误页面浇灭。明明本地测试一切正常，为什么一放进容器就找不到路由？这个问题困扰过无数开发者，而答案往往藏在那个容易被忽略的root_path参数里。

1. 为什么Docker部署会让你的API"消失"？

在本地开发时，我们习惯直接访问http://localhost:8000来测试API。但现实生产环境中，应用通常不会直接暴露在根路径下。假设你的Docker容器通过Nginx反向代理，真实的访问路径可能是：

http://your-domain.com/api/v1/users

而容器内部应用仍然在监听/users路径。这种路径不匹配就是导致404的罪魁祸首。root_path的作用就是告诉FastAPI："虽然你在内部处理/users路由，但外部请求会带着/api/v1前缀过来，请自动适配这个差异。"

典型症状检查清单：

• 直接访问容器IP和端口能正常工作
• 通过反向代理访问返回404
• OpenAPI文档能加载但所有接口测试都失败
• 浏览器控制台显示请求路径拼接错误

2. root_path的三种配置方式与实战对比

2.1 基础配置：实例化时指定

最直接的方式是在创建FastAPI实例时设置：

from fastapi import FastAPI

app = FastAPI(
    root_path="/api/v1",
    title="My API",
    descriptio