Python项目以git submodule引入外部项目时出现模块导入错误的问题咨询

问题本质 #

当你把原生以自身目录为导入根、使用平级导入逻辑的独立项目B通过git submodule嵌套进项目A时，如果你按照带项目前缀的方式导入（也就是from ProjectB.do_something import foo），Python会把ProjectB目录当成一个普通的顶层包来解析——这个时候项目B内部的from util import bar这类平级导入语句，会从项目A的根目录开始搜索util.py，自然找不到项目B自身目录下的同名文件。同时直接修改项目B内部源码的方案存在两个无法接受的硬伤：

• 改动会把项目B原生的平级导入改成带包名的绝对导入，破坏项目B独立运行时的原有逻辑，完全不适合推送到项目B的公共远程仓库
• 本地对子模块的修改属于未提交的游离变更，后续更新子模块代码、协作者重新克隆仓库时都需要重复手动修改，维护成本极高

可复用、零侵入的落地方案 #

所有方案都不需要修改项目B的任何源码，适配逻辑全部落在项目A自己的版本控制范围内，协作者拉取完整项目后可以直接生效：

• 入口文件自动注入模块搜索路径
  利用Python的sys.path机制，在项目A的入口执行文件（比如main.py）开头、导入项目B的代码之前，手动把项目B的根目录加入模块搜索路径的最高优先级位置。项目B内部的所有平级导入逻辑都会和它独立运行时保持完全一致的解析效果。
  参考代码：

  import sys
  from pathlib import Path
  
  # 定位子模块ProjectB的根目录绝对路径
  project_b_root = Path(__file__).parent / "ProjectB"
  # 将项目B根目录插入模块搜索路径最前端，保证导入解析优先级
  sys.path.insert(0, str(project_b_root))
  
  # 后续导入项目B的方法时，直接按项目B原生的顶层模块名导入即可
  from do_something import foo
  

  这个方案完全没有额外依赖，所有逻辑都写在项目A自己的代码里，协作者只要拉取了带全量子模块的项目A仓库，直接运行入口文件就可以正常跑通，完全不需要额外手动操作。

• 统一启动脚本配置环境变量
  如果项目的入口文件比较多，不想在每个入口文件重复写路径注入逻辑，可以在项目A根目录维护一个统一的开发启动脚本，在脚本里提前把项目B的根目录写入Python进程的PYTHONPATH环境变量，效果和代码内修改sys.path完全一致。
  参考启动脚本（run_dev.sh）示例：

  # 追加项目B根目录到Python模块搜索路径
  export PYTHONPATH=$PYTHONPATH:$(pwd)/ProjectB
  # 启动项目主程序
  python main.py
  

  协作者拉取仓库后，只需要执行这个统一的启动脚本就可以正常运行，不需要手动修改任何子模块文件。如果是团队共用IDE开发，还可以把这个PYTHONPATH配置写入项目共享的IDE运行配置模板，打开项目就能自动适配。

关键注意事项 #

所有路径适配逻辑必须放在项目A的版本控制范围内，绝对不要把这类适配修改提交到项目B的远程仓库，也不要在本地子模块目录做永久改动，避免后续更新子模块时出现代码冲突或者变更丢失。
插入项目B根目录到sys.path时要放在路径列表的最前端，避免和项目A自身的同名模块（比如项目A目录下也存在util.py）产生命名冲突。

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