fastapi api文档在nginx反向代理后加载失败，主因是root_path未与代理路径对齐：需配置app=fastapi(root_path="/api/v1")并设nginx为location /api/v1/ { proxy_pass http://localhost:8000/; }，同时透传host和x-forwarded-proto头。
API 文档（如 Swagger UI、OpenAPI）在 Nginx 反向代理后加载失败或链接错乱，核心原因是文档前端依赖的路径上下文（base URL）与后端实际暴露路径不一致。本地能访问，代理后 404 或资源加载失败，基本都卡在这个环节。
明确 root_path 作用：告诉 FastAPI（或同类框架）它“挂在哪”
FastAPI 默认认为自己运行在根路径 /，所以生成的 OpenAPI JSON 中 server.url 是 http://host/，Swagger UI 也据此拼接 /v3/api-docs 等请求地址。当 Nginx 把请求代理到 /api/v1 下时，必须显式告知 FastAPI：“我实际部署在 /api/v1”。
- 启动应用时加参数：
uvicorn main:app --root-path /api/v1 - 或代码中配置：
app = FastAPI(root_path="/api/v1") - 生效后，
/docs页面里所有接口链接、重定向、api-docs请求都会自动带上/api/v1前缀
同步配置 Nginx 的 proxy_pass 和路径截断规则
Nginx 转发路径若没对齐，会把前缀带进后端，导致 FastAPI 收到 /api/v1/items 却只注册了 /items，直接 404。
- 推荐写法：
location /api/v1/ { proxy_pass http://localhost:8000/; }（注意两个/都有） - 这样
/api/v1/items会被转发为/items，和root_path完全匹配 - 避免写成
proxy_pass http://localhost:8000;（无尾斜杠）——Nginx 会报错或错误拼接 - 验证方法：用
nc -l 8080模拟后端，curl 请求看原始 path 是否被正确剥离
确保 Host 头和协议头透传，避免绝对链接出错
Swagger UI 生成的某些跳转链接（如 OAuth 回调、重定向地址）依赖 Host 和 X-Forwarded-Proto。如果 Nginx 不透传，后端可能生成 http://127.0.0.1:8000/docs 这类内网地址。
- 必须设置：
proxy_set_header Host $host; - 加上：
proxy_set_header X-Forwarded-Proto $scheme;和X-Forwarded-For - 若客户端通过域名访问但 Nginx 用 IP 转发，
$host就是域名，不会变成 IP
检查静态资源路径是否被 alias 或 root 错误覆盖
Swagger UI 的 HTML/CSS/JS 文件由框架内置提供，但若 Nginx 配置了 location /static 或 location / 的 alias，可能拦截并错误返回 404。
- 不要用
alias /path匹配/docs或/redoc所在路径 - 优先使用
location /api/v1/这类精确前缀匹配，避免location /兜底干扰 - 确认没有其他
location ~ \.js$类正则块意外劫持了文档资源请求
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
