Flask迁移FastAPI后Vue Router单页路由404问题求助

问题背景 #

此前使用Flask搭配内置Vue Router的Vue前端，实现了以下功能：

• 访问localhost:80/时，Flask返回npm run build生成的HTML打包文件
• 所有API请求走localhost:80/api/YourCall路径
• 前端自有路由系统（如localhost:80/getAll）返回Vue生成的页面，该页面调用localhost:80/api/getAll获取数据

对应的Flask实现代码：

@app.route('/',defaults={'path': ''})
@app.route('/<path:path>')
def index(path):
    if path != "" and os.path.exists(app.static_folder + '/' + path):
        return send_from_directory(app.static_folder, path)
    else:
        return send_from_directory(app.static_folder, 'index.html')

迁移至FastAPI后，访问localhost:80/getAll返回404，原因是FastAPI优先匹配路由规则。尝试过以下Stack Overflow方案但未解决问题：

from fastapi.staticfiles import StaticFiles

class SPAStaticFiles(StaticFiles):
async def get_response(self, path: str, scope):
   response = await super().get_response(path, scope)
   if response.status_code == 404:
       response = await super().get_response('.', scope)
   return response

app.mount('/my-spa/', SPAStaticFiles(directory='folder', html=True), name='whatever')

可行解决方案 #

该需求完全可行，问题出在路由挂载顺序和自定义StaticFiles的实现细节上，正确实现步骤如下：

1. 核心实现思路 #

• 先注册所有API路由：FastAPI按路由注册顺序匹配请求，必须先定义/api/开头的接口，避免被静态资源路由拦截
• 自定义静态文件处理类：当请求的静态资源不存在时，返回Vue打包后的index.html，让Vue Router接管前端路由

2. 完整代码示例 #

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# 先注册所有API接口，示例：
@app.get("/api/getAll")
async def get_all_data():
    return {"data": "示例数据"}

# 自定义适配SPA的静态文件处理类
class SPAStaticFiles(StaticFiles):
    async def get_response(self, path: str, scope):
        # 尝试获取请求的静态资源
        response = await super().get_response(path, scope)
        # 若资源不存在，返回index.html交给Vue Router处理
        if response.status_code == 404:
            response = await super().get_response("index.html", scope)
        return response

# 挂载静态文件，directory指向Vue打包后的目录（通常为dist）
app.mount("/", SPAStaticFiles(directory="dist", html=True), name="spa")

3. 关键注意事项 #

• 路由顺序不可颠倒：必须先注册API路由，再挂载SPA静态文件，否则/api/请求会被当成静态资源处理
• 打包路径要正确：确保directory参数指向Vue项目npm run build生成的文件夹（默认是dist）
• 启用html=True：该参数会让StaticFiles在访问目录时自动返回目录下的index.html，配合自定义类实现前端路由跳转

内容的提问来源于stack exchange，提问作者F.Stan