直接运行子模块会触发该错误，因为Python将其视为顶层脚本（__name__ == '__main__'），而非包内模块，导致相对导入失去父级参照系；正确方式是用python -m package.submodule在项目根目录下以模块模式执行。
为什么直接运行子模块会触发 ValueError: attempted relative import beyond top-level package
因为 Python 把你当前执行的 .py 文件当作了顶层脚本（__name__ == '__main__'），而不是包的一部分。此时它没有父级包上下文，所有以 . 或 .. 开头的导入都失去参照系。
比如目录结构是 myproject/cli.py 和 myproject/core/__init__.py，你在 core/utils.py 里写了 from ..cli import main，然后执行 python core/utils.py —— 这时 utils.py 是顶层模块，.. 就试图跳到比顶层还高的地方，Python 直接报错。
-
__name__打印出来是__main__，不是core.utils，说明没被识别为包内模块 - 相对导入只在包内模块中有效，且必须由 Python 的导入系统加载，不能靠直接执行启动
- 即使目录里有
__init__.py，只要用python xxx.py启动，就绕过了包加载机制
怎么改执行方式才能让相对导入生效
核心是让 Python 以「模块身份」加载你的文件，而不是当作独立脚本。唯一可靠的方式是用 python -m 命令，并确保当前工作目录是项目根目录（即包含 myproject/ 的那一层）。
例如项目结构：
project_root/
├── main.py
└── mypackage/
├── __init__.py
├── submod/
│ ├── __init__.py
│ └── worker.py # 里面有 from .. import config
正确做法：
- 终端 cd 到
project_root - 运行
python -m mypackage.submod.worker（注意不加.py） - 这时
worker.py的__name__是mpackage.submod.worker，..才能指向mpackage
错误做法（哪怕路径对也失败）：
-
python mypackage/submod/worker.py→ 顶层脚本，必报错 -
python -m mypackage.submod.worker但当前目录不在project_root→ 找不到包
为什么把入口移到顶层 main.py 就不容易出错
因为 main.py 天然位于项目根目录，它作为唯一入口，用绝对导入加载包内模块时，完全不依赖相对路径解析逻辑。
比如 main.py 里写：
from mypackage.core import run from mypackage.submod.worker import do_work
这种写法稳定、可读、无上下文依赖。而包内模块（如 worker.py）只负责功能，不承担启动职责 —— 它们的相对导入只在被 -m 加载或被 main.py 导入时才起作用。
- 包内模块加
if __name__ == '__main__':块是危险的，除非你明确只用-m启动 - IDE 点击“运行”默认执行
python xxx.py，容易掩盖问题；要手动配置运行命令为python -m xxx - CI/CD 或 Docker 中若用
python app.py启动，务必确认app.py是顶层入口，而非包内文件
sys.path.append 能临时绕过但不该依赖
在模块开头加 sys.path.append(os.path.dirname(os.path.dirname(__file__)) 确实能让 from mypackage import x 找到模块，但它把路径硬编码进代码，破坏了可移植性。
- 路径计算容易出错，尤其跨平台时
os.path处理不一致 - 多个
append可能污染sys.path，引发模块版本冲突 - 测试环境、打包工具（如 PyInstaller）可能忽略这些动态路径
真正该检查的是：你写的那个带 .. 的导入语句，是否真的需要跨包？如果只是想复用同级功能，把它提到公共子包里，比到处修路径更干净。
最常被忽略的一点：这个错误从不发生在 import 语句本身，而是发生在「谁来执行它」—— 搞清执行上下文，比改十行代码都管用。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
