FastAPI部署Docker遇ModuleNotFoundError：无法导入database模块

可能的原因及对应解决方案 #

1. Python路径未包含/app目录 #

虽然容器里/app目录下存在database.py，但Python的sys.path可能未包含该目录，导致无法识别同级模块。

• 临时排查：在main.py开头添加以下代码，重新构建容器并查看日志输出：

  import sys
  print("Python路径列表：", sys.path)
  

• 解决方法：
  要么在main.py开头手动添加路径：

  import sys
  sys.path.append("/app")
  

  要么采用更规范的Python包结构（推荐）。

2. 未将app目录标记为Python包 #

Python要求目录下存在__init__.py文件才会将其识别为可导入的包，否则同级模块的导入会失败。

• 操作：在/app目录下创建空的__init__.py文件。
• 修改main.py中的导入语句为相对导入：

  from .database import get_session
  

3. Dockerfile的工作目录或启动命令配置错误 #

检查Dockerfile中的工作目录和启动命令是否匹配文件结构：

• 确保已设置工作目录为/app：

  WORKDIR /app
  

• 启动命令需在工作目录下执行，例如：

  CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
  

  若用Python直接启动脚本，也要保证路径正确：

  CMD ["python", "main.py"]
  

4. 文件名大小写不匹配（少见但需排查） #

本地系统（如Windows）不区分文件名大小写，但Linux容器严格区分。确认容器内的文件名是database.py，而非Database.py或其他大小写变体。

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