本文详解 Python 包内子模块间导入失败的根本原因，重点解决因误用绝对导入导致的 ModuleNotFoundError，通过修正为相对导入（如 from .directory_handler import DirectoryNameHandler）使包结构清晰、路径无关、可移植性强。
本文详解 python 包内子模块间导入失败的根本原因，重点解决因误用绝对导入导致的 `modulenotfounderror`，通过修正为相对导入（如 `from .directory_handler import directorynamehandler`）使包结构清晰、路径无关、可移植性强。
在 Python 项目中，当模块组织成嵌套包结构（如 downloader_mod/shelf.py 需要使用同级目录下的 directory_handler.py）时，错误地使用顶层模块名进行绝对导入（例如 from directory_handler import ...）是引发 ModuleNotFoundError: No module named 'directory_handler' 的最常见原因。根本问题在于：Python 解释器仅将启动脚本所在目录（即 src/）加入 sys.path，而不会自动将子包目录（如 downloader_mod/）视为独立模块搜索路径——因此 directory_handler 并非一个可被全局导入的顶层模块，而是 downloader_mod 包内的一个局部模块。
正确的解决方案是采用 显式相对导入（explicit relative import）。在 shelf.py 中，应将原错误代码：
# ❌ 错误：试图以顶层模块方式导入同包模块 from directory_handler import DirectoryNameHandler
替换为：
# ✅ 正确：使用相对导入，表示“从当前包（.）导入” from .directory_handler import DirectoryNameHandler
? 关键规则：
立即学习“Python免费学习笔记（深入）”；
- . 表示当前包（即 downloader_mod）；
- .. 表示上一级包（若存在）；
- 相对导入只能在包内模块中使用，且必须位于 __init__.py 存在的合法包结构中（您已正确添加 downloader_mod/__init__.py，符合要求）；
- 不可在直接运行的脚本中使用相对导入（如 python shelf.py 会报 ImportError: attempted relative import with no known parent package），但这不影响 downloader.py 作为入口调用包内模块——只要 shelf.py 本身不被直接执行即可。
✅ 同时，请确保以下实践已就位：
- src/ 下存在 __init__.py（可为空），使其成为可识别的顶层包（虽非强制，但推荐）；
- downloader_mod/__init__.py 已存在（您已完成）；
- 所有导入均基于包层级，而非文件系统路径；
- 无需修改 PYTHONPATH、.env 或 VS Code 配置——相对导入天然解耦环境变量，提升可维护性与跨平台兼容性。
? 补充建议：
为增强可读性与封装性，可在 downloader_mod/__init__.py 中显式导出公共接口，例如：
# src/downloader_mod/__init__.py from .shelf import ShelfData from .directory_handler import DirectoryNameHandler # 此后外部可统一使用：from downloader_mod import ShelfData, DirectoryNameHandler
最后验证：保存修改后，在 src/ 目录下运行 python downloader.py，导入将成功，且逻辑完全保持不变。这不仅修复了错误，更使模块依赖关系清晰、可静态分析，并符合 PEP 8 与现代 Python 包设计规范。
