Python 直接执行包内文件，相对导入报 no known parent package

在包内文件写了 from . import helper，直接执行这个文件却报 ImportError: attempted relative import with no known parent package。文件确实存在，也不意味着这次启动为它建立了包上下文。

下面以 Python 3 的常规包为例。问题通常出现在“包内模块”和“直接执行的脚本”混用时；虚拟环境、依赖缺失和同名模块遮蔽需要另行判断。

对照启动方式和包目录

假设目录结构如下，文件名都是示例：

project/
└── apppkg/
    ├── __init__.py
    ├── tools/
    │   ├── __init__.py
    │   └── run.py
    └── common/
        ├── __init__.py
        └── helper.py

run.py 要从同一个顶层包里的兄弟子包导入，可以写：

from ..common import helper

两点先回到 apppkg，再进入 common。如果使用下面的直接文件启动方式：

python apppkg/tools/run.py

该文件作为 __main__ 执行，而不是以 apppkg.tools.run 的身份导入。直接文件启动时，__main__.__spec__ 通常为 None，相对导入没有可据以定位的父包。仅补一个 __init__.py，不会改变这条启动命令的含义。

从包的外层目录用 -m 启动

在示例中的 project 目录执行：

python -m apppkg.tools.run

-m 接收模块名，不是文件路径，因此不要添加 .py 或写成目录斜杠。正常情况下，当前目录在模块搜索路径中，Python 可以找到 apppkg，并为入口模块设置相应的模块说明。

如果变成 No module named apppkg，先检查工作目录、实际解释器，以及包是否安装到该解释器的环境。IDE 的运行配置也需要设置正确的模块名和工作目录；在终端能运行，不代表 IDE 仍按同样方式启动。

隔离模式 -I 等选项会改变搜索路径规则，不能直接套用“当前目录一定可导入”的判断。部署脚本、定时任务和容器入口同样要明确启动目录，或按项目的安装方式提供包。

beyond top-level package 要检查顶层名称

如果进入 apppkg 目录，再运行：

python -m tools.run

此时 tools 被当成顶层包，from ..common import helper 却要求再向上一级，于是可能报 attempted relative import beyond top-level package。应回到包含 apppkg 的目录，并使用完整模块名；增加更多点不会修复错误的顶层上下文。

相对导入可以访问共同父包下的兄弟子包。它表达的是包层级，不是任意文件系统上的“向上找文件”。普通包示例中的 __init__.py 有助于明确结构，但 Python 3 的命名空间包另有规则，不能把“所有包都必须有这个文件”当成通用结论。

需要独立脚本时，把入口放在包外

如果项目需要一个直接执行的入口，可以在 project 下放一个小脚本，从包使用绝对导入，再调用包内函数。例如已有 apppkg.tools.run.main 时：

from apppkg.tools.run import main

if __name__ == "__main__":
    main()

这样包内模块保持按包导入，入口只负责启动。这里要求实际存在 main，且 apppkg 对当前解释器可导入；没有这个函数时应先按项目已有入口组织代码。不要把修改 sys.path 或把所有文件复制到一个目录作为默认解决方式。

修改前记录现有入口和工作目录，调整后检查终端、IDE 与部署入口是否一致。成功标准是原来的相对导入按预期加载目标模块，入口行为保持正确，且没有靠另一份同名文件误打误撞地通过。