本文详解 Python 多目录包结构中跨子包导入模块的规范方法，重点解决 ModuleNotFoundError: No module named 't1' 等常见导入错误，涵盖相对导入语法、__init__.py 的作用与现代 Python 兼容性说明。
本文详解 python 多目录包结构中跨子包导入模块的规范方法，重点解决 `modulenotfounderror: no module named 't1'` 等常见导入错误，涵盖相对导入语法、`__init__.py` 的作用与现代 python 兼容性说明。
在 Python 项目中，当代码按层级组织为包（如 t1/, t2/）时，模块间的正确导入是运行稳定的关键。典型错误如 from t1.test import test 报 ModuleNotFoundError: No module named 't1'，往往源于未满足 Python 包导入的两个核心前提：执行上下文需为包外顶层入口，且导入路径需符合包结构逻辑。
假设项目结构如下（推荐布局）：
project_root/
├── __init__.py # 可选（Python 3.3+ PEP 420 隐式命名空间包支持）
├── t1/
│ ├── __init__.py # 推荐保留，显式声明为包（兼容性 & 可读性更佳）
│ └── test.py
└── t2/
├── __init__.py
└── main.py # 当前执行文件（即 python t2/main.py）
此时，在 t2/main.py 中不可直接使用绝对导入 from t1.test import test，因为 t1 并非当前 Python 解释器的可导入包（未在 sys.path 中，也未作为顶层包被识别）。正确做法是采用 相对导入（relative import）：
# t2/main.py from ..t1 import test # ✅ 正确：向上跳两级（t2 → project_root），再进入 t1 # 或 from ..t1.test import some_function # 直接导入具体对象
⚠️ 注意事项：
- 相对导入仅允许在包内模块中使用（即
main.py必须作为包的一部分被运行，而非直接python t2/main.py）； - 正确执行方式应为：在
project_root/目录下运行python -m t2.main
这样 Python 才会将
project_root视为顶层包，..t1才能解析成功； - 若坚持直接运行
main.py，可临时修改路径（不推荐用于生产）：# t2/main.py 开头添加（仅调试用） import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent)) from t1 import test # ✅ 此时绝对导入生效
关于 __init__.py：Python 3.3+ 已支持隐式命名空间包（无需 __init__.py），但强烈建议保留空的 __init__.py 文件——它明确标识包边界、避免 IDE 误判、提升代码可维护性，且无任何副作用。
总结：解决跨包导入问题，关键在于理解 Python 的模块搜索机制与包执行模型。优先使用 python -m package.module 方式运行，并配合 from ..parent import module 的相对导入语法，辅以规范的 __init__.py 布局，即可稳健处理任意深度的文件结构。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
