FastAPI+React前后端合一Docker化实现建议求助

问题背景 #

我正在构建一个基于FastAPI和React的简单应用，公司工程部建议我将其Docker化为一个单一应用，而非分离的前后端。目前该应用已能正常运行，当前目录结构如下：

.
├── README.md
├── backend
│   ├── Dockerfile
│   ├── Pipfile
│   ├── Pipfile.lock
│   └── main.py
└── frontend
    ├── Dockerfile
    ├── index.html
    ├── package-lock.json
    ├── package.json
    ├── postcss.config.js
    ├── src
    │   ├── App.jsx
    │   ├── favicon.svg
    │   ├── index.css
    │   ├── logo.svg
    │   └── main.jsx
    ├── tailwind.config.js
    └── vite.config.js

我是Docker新手，仅为非前后端分离的项目构建过镜像。前后端各自拥有一个.env文件，仅包含URL、主机等简单配置。当前我分别启动前后端来运行应用，示例命令如下：

> cd frontend
> npm run dev

> cd backend
> uvicorn main:app --host 0.0.0.0 --port 8000

请问能否提供将其Docker化为单一应用的建议？

实现方案 #

核心思路 #

采用多阶段构建：先编译React前端产物，再将静态文件复制到FastAPI后端镜像中，让FastAPI同时提供API服务和静态文件托管，最终生成一个单一镜像。

步骤1：调整前端Vite配置 #

修改frontend/vite.config.js，确保构建产物适配后端静态文件路径，同时保留开发环境的API代理：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist', // 前端构建产物输出目录（默认）
    base: '/' // 配置基础路径，保证静态资源加载正常
  },
  server: {
    // 开发环境代理API请求到后端，避免跨域
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true
      }
    }
  }
})

步骤2：修改FastAPI后端代码 #

在backend/main.py中添加静态文件托管逻辑，支持SPA路由（React路由刷新不404）：

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse
import os

app = FastAPI()

# 保留原有API路由示例
@app.get("/api/health")
async def health_check():
    return {"status": "ok"}

# 配置前端静态文件路径
static_dir = os.path.join(os.path.dirname(__file__), "frontend/dist")
if os.path.exists(static_dir):
    # 挂载前端静态资源
    app.mount("/static", StaticFiles(directory=os.path.join(static_dir, "static")), name="static")
    
    # 处理SPA路由：所有非API路径返回index.html
    @app.get("/{full_path:path}")
    async def serve_spa(full_path: str):
        return FileResponse(os.path.join(static_dir, "index.html"))

步骤3：编写根目录多阶段Dockerfile #

在项目根目录创建Dockerfile，内容如下：

# 第一阶段：构建React前端
FROM node:18-alpine AS frontend-build
WORKDIR /app/frontend
COPY frontend/package*.json ./
RUN npm ci --only=production
COPY frontend/ .
RUN npm run build

# 第二阶段：构建FastAPI后端并整合前端产物
FROM python:3.11-slim
WORKDIR /app/backend
COPY backend/Pipfile backend/Pipfile.lock ./
# 安装pipenv及后端依赖
RUN pip install --no-cache-dir pipenv && pipenv install --deploy --system
COPY backend/ .
# 从第一阶段复制前端构建产物到后端目录
COPY --from=frontend-build /app/frontend/dist ./frontend/dist

# 暴露FastAPI服务端口
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

步骤4：环境变量配置 #

• 可以将前后端的.env文件合并到根目录的.env，在Dockerfile中添加复制命令：

  COPY .env ./backend/.env
  

• 或者运行容器时通过命令传入环境变量：

  docker run -p 8000:8000 --env-file .env your-image-name
  

步骤5：构建与运行 #

在项目根目录执行以下命令：

# 构建镜像
docker build -t fastapi-react-app .

# 运行容器
docker run -d -p 8000:8000 fastapi-react-app

访问http://localhost:8000即可看到React应用，API请求通过/api/xxx路径访问。

注意事项 #

• 前端代码中调用API的地址需改为/api/xxx，避免跨域问题
• 多阶段构建会自动丢弃前端构建时的node_modules和编译工具，大幅减小最终镜像体积
• 单一镜像模式更适合生产环境部署，开发环境仍推荐分离前后端容器以获得热重载能力
• 可根据实际需求调整端口、静态文件路径等配置

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