Python跨顶级包导入问题：FastAPI项目共享模型实现咨询

需求可行性 #

完全可行，将重复模型抽离到项目根目录统一管理是Python项目实现代码复用的标准做法，能有效消除重复维护成本。

步骤1：调整项目结构 #

先把app_1/models和app_2/models中的模型文件迁移到项目根目录下的models文件夹，删除原app内的models目录，最终结构如下：

project/
  models/
    __init__.py  # 建议添加空文件，确保被识别为Python包
    model_1.py
  app_1/
    file_1.py
    app_1.Dockerfile
  app_2/
    file_1.py
    app_2.Dockerfile
  docker-compose.yaml

步骤2：解决导入报错问题 #

以下三种方法任选其一，根据你的运行场景选择最适配的：

方法1：动态添加项目根目录到Python路径（通用型，适配本地/容器环境） #

在每个app的启动文件（如app_2/file_1.py）开头添加代码，将项目根目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取项目根目录的绝对路径（当前脚本的父级父级目录）
project_root = Path(__file__).resolve().parent.parent
sys.path.append(str(project_root))

# 现在可以直接导入模型
from models.model_1 import Model

这种方法不依赖运行方式，无论直接启动脚本还是通过容器运行都能生效。

方法2：使用相对导入（需以模块方式运行） #

如果在项目根目录下以模块方式启动应用（而非直接运行脚本文件），可以使用相对导入：
在app_2/file_1.py中：

# 从上级目录的models包导入
from ..models.model_1 import Model

启动命令需改为：

# 在project目录下执行
python -m app_2.file_1

注意：不能直接运行python app_2/file_1.py，否则Python会将app_2视为顶级包，触发"attempted relative import beyond top-level package"错误。

方法3：在Docker环境中配置PYTHONPATH（容器专属） #

在每个app的Dockerfile中设置环境变量，指定项目根目录为Python模块搜索路径：
以app_2.Dockerfile为例：

# 假设将项目代码复制到容器内的/project目录
WORKDIR /project
COPY . .

# 设置PYTHONPATH指向项目根目录
ENV PYTHONPATH=/project

# 启动FastAPI应用
CMD ["uvicorn", "app_2.file_1:app", "--host", "0.0.0.0", "--port", "8000"]

也可以在docker-compose.yaml中统一配置所有服务的环境变量：

services:
  app_1:
    build:
      context: .
      dockerfile: app_1/app_1.Dockerfile
    environment:
      - PYTHONPATH=/project
    ports:
      - "8001:8000"
  app_2:
    build:
      context: .
      dockerfile: app_2/app_2.Dockerfile
    environment:
      - PYTHONPATH=/project
    ports:
      - "8002:8000"

配置完成后，容器内的代码可直接使用：

from models.model_1 import Model

注意事项 #

• 务必在models目录下添加空的__init__.py文件，确保Python将其识别为合法包（Python 3.3+支持无该文件的命名空间包，但显式添加可避免潜在兼容问题）。
• 若使用方法1，建议用resolve()确保路径为绝对路径，避免因工作目录变化导致路径错误。

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