Python 中正确使用相对导入：以包结构为基础的模块引用实践

本文详解如何通过规范的包结构和正确的运行方式解决 ImportError: attempted relative import with no known parent package 问题，重点说明 __init__.py 的作用、相对导入的生效前提及推荐的绝对导入方案。

本文详解如何通过规范的包结构和正确的运行方式解决 `importerror: attempted relative import with no known parent package` 问题，重点说明 `__init__.py` 的作用、相对导入的生效前提及推荐的绝对导入方案。

在 Python 中，__init__.py 文件的存在确实标志着一个目录可被识别为包（package），但仅此并不足以让相对导入（如 from ..SignIn import sign_in）正常工作——关键在于 模块的执行上下文。你的项目结构如下：

soar/
  __init__.py      # 标记 soar 为顶层包
  SignIn.py
  SignInOTP.py
  90min/
    __init__.py    # 标记 90min 为子包
    main.py

该结构本身是合法的包布局，但问题出在如何运行 main.py。

❌ 错误做法：直接执行脚本文件

python 90min/main.py        # × 不会将 soar 视为包
python -m '.\90min\main.py' # × 语法非法，且未指定包路径

此时 Python 将 main.py 视为独立脚本（__name__ == '__main__'），其 __package__ 为 None，因此所有 .. 形式的相对导入均失败，报错：

ImportError: attempted relative import with no known parent package

✅ 正确做法：以包为单位运行模块

必须通过 -m 参数，从包根目录外启动，并显式指定完整模块路径：

立即学习“Python免费学习笔记（深入）”；

LOVO AI

AI人声和文本转语音生成工具

下载

# 在 soar 的父目录下执行（即包含 soar/ 的目录）
python -m soar.90min.main

此时：

• Python 将 soar 识别为顶层包（因 soar/__init__.py 存在）；
• soar.90min.main 被加载为子模块，其 __package__ 自动设为 'soar.90min'；
• 相对导入 from ..SignIn import sign_in 才能向上追溯到 soar.SignIn，顺利解析。

✅ 补充验证：在 main.py 开头添加 print(__package__)，成功运行时应输出 soar.90min。

? 推荐实践：优先使用绝对导入（更清晰、更健壮）

尽管相对导入可行，但 PEP 8 及主流风格指南（如 Google Python Style Guide）明确建议：优先使用绝对导入。它语义明确、不易出错，且不依赖执行方式：

# soar/90min/main.py
from soar.SignIn import sign_in
from soar.SignInOTP import sign_in_otp

if __name__ == "__main__":
    sign_in()
    sign_in_otp()

这样，无论你用 python -m soar.90min.main 还是（在正确 PYTHONPATH 下）直接 python 90min/main.py，只要环境能定位 soar 包，导入均有效。

⚠️ 注意事项与常见误区

• __init__.py 文件可以为空，但必须存在（Python 3.3+ 支持 namespace packages，但此处不适用）；
• 运行命令必须在 soar 的同级目录下执行，而非 soar/ 内部；
• 确保当前工作目录未意外包含同名 soar 模块（如本地 soar.py 文件），否则会覆盖真实包；
• PyCharm 中若未显示包图标，请右键 soar/ → Mark Directory as → Sources Root，并确认解释器路径包含该目录。

✅ 总结

遵循以上原则，即可彻底规避“relative import with no known parent package”错误，构建清晰、可维护的多层 Python 包结构。