Python项目使用git子模块作为依赖时的导入异常问题咨询

问题场景 #

现有独立项目Project_A，目录结构如下：

Project_A/
├── __init__.py
├── source/
│   ├── package_a/
│   │   ├── __init__.py
│   │   └── module_a.py
│   └── package_b/
│       ├── __init__.py
│       └── module_b.py
├── tests/
│   ├── __init__.py
│   └── tests.py
└── Runner.py

Project_A内部module_b.py原本使用相对导入：

# module_b.py
from ..package_a.module_a import class_a

切换为绝对导入风格后，原方案是在Project_A根目录的__init__.py中添加路径注入代码，将项目根目录加入系统路径：

# Project_A 根目录 __init__.py
import sys
from os.path import dirname, abspath
sys.path.append(dirname(abspath(__file__)))

该方案在Project_A独立运行时正常，但通过git submodule将Project_A作为Project_B的第三方依赖引入时，会触发ImportError。Project_B目录结构如下：

Project_B/
├── __init__.py
├── source/
│   └── package_c/
│       ├── __init__.py
│       └── module_c.py
├── tests/
│   ├── __init__.py
│   └── tests.py
├── Runner.py
├── .gitmodules
└── thirdparty/
    └── Project_A/  # git子模块

问题成因：Project_B运行时，Python解释器会按照绝对导入路径查找package_a.module_a.class_a，但Project_B的根目录及默认系统路径下不存在顶层package_a包，导致导入失败。在所有__init__.py中重复添加路径追加逻辑违反DRY原则，不是合理方案。

核心问题根源 #

在包的__init__.py中手动修改sys.path本身就是Python项目的非标准hack行为：这类逻辑只有当项目根目录作为脚本执行入口、包层级和预期一致时才会生效，一旦项目被作为子包嵌套到其他项目中，路径注入的相对位置会发生变化，同时破坏Python包的默认导入解析规则，必然会出现导入错误。

优雅解决方案（按推荐优先级排序） #

• 方案1：使用标准打包+可编辑安装（最推荐，完全符合Python生态规范） #

  不需要写任何sys.path.append逻辑，只需要给Project_A添加最小化的pyproject.toml配置文件，放在Project_A根目录下：

  [build-system]
  requires = ["setuptools>=61.0"]
  build-backend = "setuptools.build_meta"
  
  [project]
  name = "project-a"
  version = "0.1.0"
  
  [tool.setuptools.packages.find]
  where = ["."]
  include = ["source*"]
  

  之后不管是独立开发Project_A，还是把它作为Project_B的子模块，只需要在对应虚拟环境里执行可编辑安装即可：

  # 独立开发Project_A时，在Project_A根目录执行
  pip install -e .
  
  # Project_B引入子模块后，在Project_B根目录执行
  pip install -e ./thirdparty/Project_A
  

  安装完成后，不管是Project_A内部的绝对导入（写为from source.package_a.module_a import class_a），还是Project_B里跨项目导入（写法和Project_A内部完全一致）都可以正常运行，完全不需要手动修改任何路径，一次配置永久生效，和所有Python标准工具链（pytest、mypy、打包工具等）完全兼容。

• 方案2：统一使用相对导入，彻底规避路径依赖 #

  如果暂时不想引入打包配置，可以直接废弃之前的绝对导入+路径注入的写法，Project_A内部所有跨模块导入全部使用相对导入（原有module_b.py的相对导入写法本身是正确的，不需要修改）。
  在Project_B中导入Project_A的内容时，带上完整的子模块路径前缀即可：

  # module_c.py 内的导入
  from thirdparty.Project_A.source.package_a.module_a import class_a
  

  这种写法不需要修改sys.path，只要两个项目的最外层入口脚本Runner.py放在各自项目根目录（Python会自动把脚本所在目录加入搜索路径），导入就可以正常运行。注意这种方式下不要把Project_A的根目录单独加进sys.path，否则会出现同一份模块被两个不同路径加载的隐蔽问题。

• 方案3：路径注入逻辑只保留在执行入口，不放在包的__init__.py中 #

  如果一定要用路径注入的方式，绝对不要把sys.path.append逻辑写在任何包的__init__.py里——这类初始化代码会在包被导入时执行，嵌套场景下很容易出现路径冲突。你只需要把路径追加逻辑写在每个项目最外层的入口脚本（也就是两个项目根目录下的Runner.py）最顶部即可：

  # Runner.py 最顶部
  import sys
  from os.path import dirname, abspath
  # 只把当前项目的根目录加入搜索路径，子模块的路径不需要额外处理
  sys.path.append(dirname(abspath(__file__)))
  

  这种方式下，不管项目独立运行还是作为子模块被引用，入口脚本只会注入当前项目的根路径，子模块内部的导入会按照自身的包层级解析，不会出现找不到包的问题，也不需要在每个__init__.py里重复写路径逻辑。

注意：不要使用在所有__init__.py里重复加路径的方案，这种做法不仅违反DRY原则，还很容易造成循环导入、模块重复加载、命名空间冲突等很难排查的问题。

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