FastAPI挂载Chainlit与React静态路由时出现404 NotFound错误

问题根源 #

FastAPI的路由挂载采用前缀匹配规则：

• 当你将StaticFiles挂载到根路径/时，它会匹配所有请求（所有路径都以/开头），后续挂载的路由会被完全拦截，无法触发。
• 先挂载/chainlit再挂载/时，/路径的404通常是因为React构建产物的路径配置错误，导致StaticFiles无法找到正确的index.html文件。

解决方法 #

不要直接将StaticFiles挂载到/，而是通过路由捕获所有非Chainlit的请求，返回React的入口文件，同时单独挂载静态资源：

1. 调整FastAPI代码

from fastapi import FastAPI
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles
from chainlit.server import mount_chainlit

app = FastAPI()

# 优先挂载Chainlit路由，确保/chainlit请求被优先处理
mount_chainlit(app=app, target="cl_app.py", path="/chainlit")

# 挂载React构建后的静态资源目录（根据你的实际文件结构调整）
app.mount("/static", StaticFiles(directory="../frontend/dist/static"), name="static")
app.mount("/assets", StaticFiles(directory="../frontend/dist/assets"), name="assets")

# 捕获所有非Chainlit的请求，返回React入口文件，适配React的BrowserRouter路由
@app.get("/{full_path:path}")
async def serve_react_app(full_path: str):
    return FileResponse("../frontend/dist/index.html")

2. 修正React构建配置

• 如果使用Vite：在vite.config.js中设置base: "/"（确保静态资源路径正确）：

  export default defineConfig({
    base: "/",
    // 其他配置...
  })
  

• 如果使用Create React App：在package.json中设置"homepage": "."：

  {
    "homepage": ".",
    // 其他配置...
  }
  

3. 重新构建React项目

执行构建命令生成正确的dist目录：

# Vite项目
npm run build

# Create React App项目
npm run build

这样调整后，/路径会正常加载React前端，/chainlit路径也能正确触发Chainlit应用。

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