17370845950

本文讲解如何通过相对导入（`from .child import child`）统一解决 python 项目中因执行方式不同导致的模块导入不一致问题，适用于 `python -m unittest discover` 和 `python -m project_name` 两种主流运行场景。

在 Python 项目中，当生产代码与测试代码分离存放（如 project_name/ 与 tests/ 并列），且需支持多种运行方式（直接运行包、执行单元测试、导入使用等）时，常遇到 ImportError：同一行 import 在 __main__.py 中成功，却在测试中失败——根源在于 Python 对 __package__ 的动态赋值机制随入口点变化而不同。

根本原因：__package__ 的上下文敏感性

Python 解析 import 语句时，会依据当前模块的 __package__ 属性决定相对导入的基准包路径。观察以下关键差异：

• 执行 python project_name 时：
  project_name/__main__.py 被作为脚本运行（__name__ == '__main__'），__package__ 被设为空字符串 ''；但其导入的子模块（如 submodule/parent.py）因属于已加载的包 project_name.submodule，其 __package__ 被设为 'submodule'（注意：不是完整路径）。

• 执行 python3 -m unittest discover 时：
  project_name/__init__.py 被显式导入，因此整个 project_name 包被正确识别，其子模块的 __package__ 均为 'project_name.submodule'。

这意味着：

• from submodule.child import Child 仅在 __package__ == 'submodule' 时有效（适用于直接运行），但在测试中因 __package__ == 'project_name.submodule' 而失败；
• from project_name.submodule.child import Child 则只在测试中有效，直接运行时因顶层包未被导入而报错；
• 绝对导入依赖包的全局可见性，而相对导入则锚定当前包结构，天然解耦执行入口。

✅ 推荐方案：统一使用显式相对导入

将 project_name/submodule/parent.py 中的导入语句改为：

# project_name/submodule/parent.py
from .child import Child  # ✅ 正确：显式相对导入

class Parent:
    def __init__(self):
        self.child = Child()

    def hello(self):
        self.child.hello()

✅ 优势说明：

• . 表示当前包（即 project_name.submodule），无论 __package__ 是 'submodule' 还是 'project_name.submodule'，Python 均能正确解析为同一物理位置；
• 不依赖 sys.path 修改或 PYTHONPATH 环境变量，符合 PEP 8 与可移植性最佳实践；
• 兼容所有标准运行方式：python -m project_name、python3 -m unittest discover、pytest 及交互式导入。

? 调试技巧：可视化导入上下文

在排查导入问题时，在模块顶部添加诊断日志（临时）：

# 开发时加入（上线前移除）
print(f"Running {__file__}\n    __package__={__package__!r}\n    __name__={__name__!r}")

该输出清晰揭示当前模块的加载上下文，是定位 ImportError 的黄金工具。

⚠️ 注意事项与补充建议

• 确保所有目录含 __init__.py：project_name/、project_name/submodule/、tests/ 必须存在（可为空），否则 Python 不视其为包，相对导入将失效；
• 避免隐式相对导入（如 import child）：已被 Python 3 废弃，必须使用 from . import child 或 from .child import Child；
• 测试文件中的导入应始终使用绝对路径：如 from project_name.submodule.parent import Parent，因其位于独立包 tests/ 下，与 project_name/ 无父子关系；
• 若项目需支持 pip install -e . 开发安装，应在 setup.py 或 pyproject.toml 中正确定义 packages，确保 project_name 可被发现。

通过坚持「子模块内优先使用显式相对导入」这一原则，即可一劳永逸地消除因执行方式切换引发的导入混乱，大幅提升项目结构的健壮性与可维护性。