Python3导入系统原理与相对导入使用问题咨询

核心规则前置 #

• 所有import语句查找模块时，只会按顺序遍历sys.path列表中记录的目录，不会默认将当前文件所在目录加入搜索范围；只有被直接作为入口运行的脚本所在的目录，才会被自动插入sys.path的首位。
• 绝对导入的搜索起点始终是sys.path中的顶层目录，和当前文件所处的包层级无关。
• 相对导入仅能在处于包上下文的模块中使用，搜索依据是当前模块的__package__属性记录的包层级；如果直接将某个.py文件作为入口脚本运行，该文件的__package__值为None，完全无法使用相对导入——这是Python的明确设计，不是功能缺陷。
• 你之前对__name__变量的认知是正确的，但遗漏了上述sys.path和包上下文两个核心逻辑，这是所有报错的根源。

报错原因拆解 #

问题A：初始写法报No Module Named错误 #

运行main.py时，自动加入sys.path的是项目根目录Main/，此时Python仅能识别Main/下的顶层包和模块（即main.py、PackageOne包）。
你在PackageOne/__init__.py中写import PackageTwo, ModuleOne时，Python会去sys.path的所有顶层目录下查找名为PackageTwo、ModuleOne的顶层模块/包，但这两个对象都在PackageOne内部，不属于顶层目录下的内容，自然会报找不到的错误。同理PackageTwo/__init__.py中写import ModuleTwo时，ModuleTwo属于PackageOne.PackageTwo下的模块，不在顶层搜索路径中，也会触发相同报错。

问题B：改全路径绝对导入后，直接运行__init__.py报错 #

将导入语句改为从PackageOne开头的绝对导入后，运行根目录下的main.py时，因为Main/在sys.path中，可以正常找到顶层的PackageOne包，所以运行正常。
但如果直接运行包内的__init__.py，自动加入sys.path的是该__init__.py所在的目录：例如运行PackageOne/__init__.py时，加入搜索路径的是Main/PackageOne/，Python会在这个目录下查找顶层的PackageOne包，自然找不到，触发No Module Named 'PackageOne'错误。

这里需要纠正一个常见认知偏差：Python的包设计本身就不要求包内所有文件同时支持“作为入口直接运行”和“被其他代码导入”两种场景。包内模块的定位是供外部导入复用的，项目入口脚本应该统一放在包结构的外层（即你当前main.py所在的根目录位置）。

相对导入的正确用法 #

相对导入通过.标记当前包层级，规则非常明确：

• 单个.代表当前模块所在的包目录
• 连续的..代表当前包的上一级父目录，层级可以按需叠加
• 相对导入不会遍历sys.path，仅在当前模块所属的包结构内查找目标
• 禁止在直接运行的入口脚本中使用相对导入

对应你的目录结构，将包内的导入全部替换为相对导入即可满足被外部导入的正常运行需求：

1. 修改PackageOne/__init__.py内容：

print(f"From ParentPackage, Name:{__name__}")
from . import PackageTwo, ModuleOne

这里的.指代当前PackageOne包本身，会直接在PackageOne目录下查找PackageTwo子包和ModuleOne模块，不需要写全PackageOne的前缀。

2. 修改PackageTwo/__init__.py内容：

print(f"From ChildPackage, Name:{__name__}")
from . import ModuleTwo

这里的.指代当前PackageTwo包，会直接查找同目录下的ModuleTwo模块。

修改完成后，在根目录运行main.py即可正常执行，不会出现模块找不到的问题。

兼顾包内模块测试运行的方案 #

如果确实需要运行包内某个模块的测试逻辑，不要直接进入模块所在目录执行python xxx.py，应该在项目根目录（即Main/层）使用-m参数按模块全限定名运行，例如要运行ModuleTwo.py，执行以下命令即可：

python -m PackageOne.PackageTwo.ModuleTwo

这种运行方式下，Python会自动将当前执行命令的目录（项目根目录）加入sys.path，同时正确识别模块的包层级，哪怕模块内写了相对导入也能正常运行，不会触发报错。

避坑提示 #

• 不要将项目根目录、包内模块命名为和Python内置模块、第三方依赖同名的名称，否则会出现导入冲突
• 不要通过手动修改sys.path的方式凑导入路径，这类写法在项目迁移、换运行环境时大概率失效
• 所有入口脚本统一放在项目根目录，不要嵌套到包结构内部，可以避开90%以上的Python导入问题

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