Python3 自定义包相对导入函数ModuleNotFound报错解决方案

问题根源 #

该报错本质是Python模块搜索路径和导入规则不匹配：

• 直接运行app.py时，Python会自动将app.py所在的superParent目录加入搜索路径，因此custom_package作为顶层包可被识别
• 包内的file1.py/file2.py运行时的顶层命名空间以启动入口的搜索路径为准，无法直接识别同目录下的其他模块

具体解决方案（完全无需修改sys.path） #

1. 包内模块互相导入使用相对导入 #

custom_package目录下的所有内部导入统一使用点开头的相对导入语法，无需依赖顶层包名，适配性更强。
示例：file1.py中导入file3.py的func_efg

from .file3 import func_efg

2. 顶层导入的正确使用方法 #

你提到的from custom_package.file1 import func_abc本身符合Python导入规范，运行报错优先排查两个场景：

• 运行脚本的工作目录不在superParent下：比如你在superParent的父目录执行python superParent/app.py，此时Python会将父目录加入搜索路径，找不到custom_package包导致报错
• custom_package下的__init__.py文件损坏：正常情况下空的__init__.py即可满足包识别要求

如果需要在任意路径下都能正常启动app.py，使用Python的-m参数以模块方式运行即可：

# 执行路径为superParent的父目录时
python -m superParent.app

# 执行路径为superParent目录时
python -m app

3. 简化导入的可选配置 #

如果希望进一步简化顶层导入写法，可以在custom_package/__init__.py中提前导出需要对外暴露的函数：

# custom_package/__init__.py
from .file1 import func_abc
from .file2 import func_your_function

配置后可以直接在app.py中直接导入：

from custom_package import func_abc

AKS部署适配 #

容器化部署时，直接将superParent目录设置为容器的工作目录，启动命令使用python app.py即可，无需任何额外路径配置，完全符合生产环境规范。

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