本文详解 Python 包结构中跨子目录导入模块的规范方法，重点解决 ModuleNotFoundError: No module named 't1' 等常见导入错误，涵盖相对导入语法、__init__.py 的作用与现代 Python 兼容性说明，并提供可立即验证的目录结构与代码示例。
本文详解 python 包结构中跨子目录导入模块的规范方法，重点解决 `modulenotfounderror: no module named 't1'` 等常见导入错误，涵盖相对导入语法、`__init__.py` 的作用与现代 python 兼容性说明，并提供可立即验证的目录结构与代码示例。
在 Python 项目中，当模块分布在不同子目录（如 t1/test.py 和 t2/main.py）时，直接使用 import t1.test 或 from t1 import test 往往会触发 ModuleNotFoundError——这并非代码写错，而是 Python 解释器未将当前项目根目录识别为可导入的包路径，或导入方式违反了模块解析规则。
✅ 正确做法是：在 t2/main.py 中使用相对导入（前提是 main.py 本身作为包内模块被运行）：
# t2/main.py from ..t1 import test # ✅ 两个点 '..' 表示向上跳一级目录，再进入 t1 包 # 或 from ..t1.test import some_function
⚠️ 但该语法生效需满足两个关键前提：
-
目录必须构成有效包结构：
即每个参与导入的目录（包括根目录、t1、t2）均需包含__init__.py文件（即使为空）。虽然 Python 3.3+ 支持隐式命名空间包（PEP 420），但显式添加__init__.py能确保兼容性与行为确定性，强烈推荐保留。推荐目录结构如下：
立即学习“Python免费学习笔记（深入）”；
提示词大师-python版下载图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
project_root/ ├── __init__.py # 根包标识（必需） ├── t1/ │ ├── __init__.py # t1 是包 │ └── test.py └── t2/ ├── __init__.py # t2 是包 └── main.py # 此文件将作为模块运行，而非脚本 -
必须以模块方式运行
main.py：
❌ 错误方式（直接执行脚本）：cd project_root/t2 python main.py # ⚠️ 此时 __name__ == '__main__'，相对导入失败
✅ 正确方式（从项目根目录以
-m模块参数运行）：cd project_root python -m t2.main # ✅ __name__ == '__main__' 且 __package__ 被正确设置，支持相对导入
? 补充说明：
-
若你希望
main.py可同时作为脚本和模块运行，可在其末尾添加兼容逻辑：# t2/main.py if __name__ == "__main__": try: from ..t1 import test except ImportError: # 回退到绝对导入（需确保 project_root 在 sys.path 中） import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent)) from t1 import test test.run() # 示例调用 绝对导入（如
from t1 import test）仅在project_root已加入sys.path时有效，可通过环境变量PYTHONPATH=project_root或启动时动态追加实现，但相对导入更安全、更符合 PEP 8 包设计规范。
总结：解决跨目录导入的核心在于理解 Python 的包上下文与模块执行模式。优先采用 from ..<parent> import <module></module></parent> 相对导入 + python -m <package.module></package.module> 运行方式，并辅以规范的 __init__.py 布局，即可稳定、可维护地管理复杂项目结构。
