FastAPI部署Flutter-web并集成离线Swagger遇404及API失效问题求助

核心问题 #

1. 静态文件路由与API路由冲突：将StaticFiles挂载到根路径/时，会拦截所有请求，包括/start、/docs这类API路由，导致API无法正常访问。
2. 根路径无匹配路由：挂载到/static时，访问localhost:9100/没有对应路由处理，返回404。
3. Swagger资源路径错误：当前配置的swagger_js_url和swagger_css_url为相对路径，在/docs页面加载时会拼接成错误路径，导致资源无法找到。

具体修复步骤 #

1. 调整静态文件挂载与路由配置 #

将Flutter-web打包产物放在static目录下，通过以下方式处理路由冲突和根路径访问：

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, JSONResponse
from fastapi.staticfiles import StaticFiles
from fastapi.openapi.docs import get_swagger_ui_html
import status
from pydantic import BaseModel

# 定义请求体模型（修复原代码未定义的参数类型问题）
class StartRequest(BaseModel):
    s: str

app = FastAPI(debug=True, docs_url=None, redoc_url=None)

# 挂载包含Flutter产物和Swagger资源的静态目录
app.mount("/static", StaticFiles(directory="static", html=True), name="static")

# 根路径返回Flutter的index.html
@app.get("/", response_class=HTMLResponse)
async def root():
    with open("static/index.html", "r", encoding="utf-8") as f:
        return HTMLResponse(content=f.read())

# 处理Flutter单页应用路由 fallback：未匹配API的路由都返回index.html
@app.route("/{full_path:path}", methods=["GET"])
async def catch_all(request: Request):
    with open("static/index.html", "r", encoding="utf-8") as f:
        return HTMLResponse(content=f.read())

# 修正Swagger资源为绝对路径
@app.get("/docs", include_in_schema=False)
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,
        title=app.title + " - Swagger UI",
        oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url,
        swagger_js_url="/static/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger-ui.css",
    )

# 修正API请求体解析逻辑
@app.post("/start")
def start_app(req: StartRequest):
    return JSONResponse(status_code=status.HTTP_400_BAD_REQUEST, content={"data": "test"})

2. 关键修正点 #

• 请求体类型修复：原代码中String未定义，改用Pydantic的BaseModel定义请求体，确保FastAPI能正确解析参数。
• Swagger路径修正：将资源路径改为绝对路径/static/...，避免在/docs页面加载时出现路径拼接错误。
• 单页路由 fallback：添加/{full_path:path}路由，处理Flutter-web的前端路由，解决页面刷新后404的问题。
• 根路径处理：直接返回Flutter的index.html，解决访问localhost:9100/的404问题。

3. 项目结构要求 #

确保项目结构符合以下格式：

project/
├── main.py
└── static/
    ├── index.html
    ├── flutter.js
    ├── （其他Flutter-web打包生成的文件）
    ├── swagger-ui-bundle.js
    └── swagger-ui.css

验证 #

启动Uvicorn服务后：

• 访问localhost:9100/：正常加载Flutter-web前端页面；
• 访问localhost:9100/start：API接口正常响应；
• 访问localhost:9100/docs：正常加载离线Swagger文档。

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