本文详解 Python 项目中因绝对导入误用导致的 ModuleNotFoundError，重点讲解如何在子包内正确使用相对导入（如 from .directory_handler import DirectoryNameHandler）替代错误的顶层模块引用，从而修复跨模块调用时的路径解析失败问题。
本文详解
python
项目中因绝对导入误用导致的 `modulenotfounderror`，重点讲解如何在子包内正确使用相对导入（如 `from .directory_handler import directorynamehandler`）替代错误的顶层模块引用，从而修复跨模块调用时的路径解析失败问题。
在 Python 包结构中，模块导入行为高度依赖于
执行上下文
与
导入语法类型
。你遇到的错误：
根本原因在于：shelf.py 中使用了
绝对导入
from directory_handler import DirectoryNameHandler，但 Python 解释器在运行 downloader.py 时，仅将 src/ 目录加入 sys.path（即模块搜索路径），而
不会自动将 src/downloader_mod/ 视为可导入的顶层包
。因此，directory_handler 被当作一个独立的顶级模块查找，自然失败。
⚠️ 关键误区：
shelf.py 属于 downloader_mod 子包，它内部对同级模块（如 directory_handler.py）的引用，
不应使用绝对导入
（from directory_handler ...），
也不应错误地写成 from downloader_mod.directory_handler ...（这会引发循环导入或冗余路径依赖），
正确方式是使用
显式相对导入
（explicit relative import），明确表达“本包内的兄弟模块”。
✅ 正确修复方案（修改 src/downloader_mod/shelf.py）：
Python 3.14.3
微软官方的 Python 扩展，是 VS Code 安装量最高的扩展（209M+）。集成 IntelliSense（通过 Pylance）、调试（通过 Python Debugger）、代码检查、格式化、重构和单元测试等功能。支持 Jupyter Notebook、虚拟环境管理和多 Python 版本切换。
下载
立即学习
“
Python免费学习笔记（深入）
”；
? 补充说明：
单个点 . 表示
当前包
（即 downloader_mod）；
from .directory_handler 等价于 from downloader_mod.directory_handler，但语义更清晰、解耦更强；
相对导入只能在
包内模块中使用
，且要求该模块被作为包的一部分导入（而非直接执行）。这也是为什么你单独运行 shelf.py 会报错（ImportError: attempted relative import with no known parent package）——此时它不是以包模块身份加载的。
? 配套注意事项：
确保 src/downloader_mod/__init__.py 存在（你已添加，很好）；
src/__init__.py 可选但推荐存在，使 src 成为命名空间包（尤其在复杂项目中）；
不要修改 PYTHONPATH 来绕过此问题
——这属于设计层面的路径误用，而非环境配置缺陷；
VS Code 的调试配置（如 launch.json）中，建议显式指定 "cwd": "${workspaceFolder}/src" 和 "module": "downloader" 或 "args": ["downloader.py"]，确保工作目录和入口一致；
若未来需从 src/ 外部调用 downloader_mod 功能，应在 src/__init__.py 或 src/downloader_mod/__init__.py 中合理导出接口，避免外部代码直接深挖子模块。
? 总结：
Python 的模块系统遵循“显式优于隐式”原则。当模块位于同一包内时，
优先使用相对导入
；当跨包引用时，才使用绝对导入（如 from downloader_mod.directory_handler import ...）。这一规范不仅解决 ModuleNotFoundError，更能提升代码可维护性、可移植性与 IDE 支持度（如自动补全、跳转、重构）。
ModuleNotFoundError: No module named 'directory_handler'# ✅ 正确：使用相对导入（点号表示当前包）
from .directory_handler import DirectoryNameHandler
class ShelfData:
def __init__(self, data_dict=None):
self.initialize_shelf_dict()
if data_dict is not None:
self.add_data_to_shelf_dict(data_dict)
dn = DirectoryNameHandler(self.shelf_name, self.creation_date)
self.simple_dir = dn.simple_dir