Docker部署FastAPI应用报错：无法在/home找到__main__模块

问题背景 #

本地可正常运行FastAPI应用，之前在docker-compose.yaml中配置command: uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000时Docker部署正常，当时main.py中无uvicorn调用。将uvicorn启动逻辑移入main.py后，Docker启动报错：

/.venv/bin/python: can't find '__main__' module in '/home'

仅Docker部署出问题，本地运行正常。

目录结构 #

├── backend
│   ├── .docker
│   │   ├── Dockerfile
│   ├── __init__.py
│   ├── .env
│   ├── main.py
├── docker-compose.yaml

相关配置与代码 #

docker-compose.yaml #

version: "3.9"

services:
  backend:
    build:
      context: ./backend
      dockerfile: .docker/Dockerfile
    env_file:
      - ./backend/.env
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - 8000:8000
    volumes:
      - .:/home

backend/.docker/Dockerfile #

FROM python:3.11.3-slim-buster as base

# Setup env
ENV LANG C.UTF-8
ENV LC_ALL C.UTF-8

# Prevent Python from writing .pyc files to disk
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONFAULTHANDLER 1
# Ensure Python output is sent straight to terminal 
ENV PYTHONUNBUFFERED 1

FROM base AS python-deps

# Update container essentials
RUN apt-get update \
  && apt-get install -y --no-install-recommends \
    gcc postgresql-client \
  && apt-get clean

# Install pipenv
RUN pip install --upgrade pip
RUN pip install pipenv

# Install python dependencies in /.venv
COPY Pipfile .
COPY Pipfile.lock .
RUN PIPENV_VENV_IN_PROJECT=1 pipenv install --deploy

FROM base AS runtime

# Copy virtual env from python-deps stage
COPY --from=python-deps /.venv /.venv
ENV PATH="/.venv/bin:$PATH"

WORKDIR /home

# Install application into container
COPY . .

CMD python . main.py

backend/.env #

COMPOSE_PROJECT_NAME=i_need_help

ENV=dev

APP_MODULE=app
HOST=0.0.0.0
PORT=8000

backend/main.py #

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI(
  title="I Need Help",
  version="0",
)

@app.get("/health")
async def health() -> JSONResponse:
  return { "message": "OK" }

if __name__ == "__main__":
  import os
  import uvicorn

  uvicorn.run(
    os.getenv("APP_MODULE"),
    host=os.getenv("HOST"),
    port=int(os.getenv("PORT")),
    reload=True
  )

问题根源 #

1. Dockerfile的CMD语法错误：python . main.py不是正确的Python脚本运行命令，Python无法识别该格式。
2. 卷挂载路径错误：docker-compose.yaml中volumes: - .:/home将项目根目录挂载到容器/home，导致main.py位于/home/backend/main.py，而非WORKDIR/home下。
3. 环境变量配置错误：.env中APP_MODULE=app指向不存在的模块，实际FastAPI实例app位于main模块中。

修复步骤 #

1. 修正Dockerfile的CMD命令 #

将Dockerfile末尾的错误CMD替换为正确的运行命令：

CMD python main.py

2. 调整卷挂载路径 #

修改docker-compose.yaml中的volumes配置，将backend目录直接挂载到容器/home，确保文件结构与构建时一致：

volumes:
  - ./backend:/home

3. 修正环境变量 #

更新backend/.env中的APP_MODULE，指向正确的模块与实例：

APP_MODULE=main:app

4. 验证与重启 #

执行以下命令重新构建并启动容器：

docker-compose down
docker-compose build
docker-compose up

访问http://localhost:8000/health，若返回{"message": "OK"}则说明修复成功。

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