直接运行含相对导入的.py文件必报错，因__package__为none导致无法解析相对路径；正确做法是用python -m配合包结构执行，确保__package__被正确设置。
直接运行含相对导入的.py文件必报错
只要模块里写了 from ..utils import logger 这类语句，再用 python src/core/processor.py 直接执行，就一定会触发 ValueError: attempted relative import beyond top-level package。这不是代码写错了，而是 Python 根本没把它当“包里的模块”来加载——__name__ 是 '__main__'，__package__ 是 None，连解析相对路径的基准都没有。
常见误操作包括：
- 在 IDE 里右键单击子模块 → “Run 'xxx.py'”
- 终端里 cd 进某个子目录再执行
python worker.py - 脚本开头有
if __name__ == '__main__':，但没做任何兜底处理
python -m 才是相对导入的合法入口
python -m 命令会强制把当前工作目录当作顶层包根目录，并根据点号路径推导出 __package__ 值。比如项目结构是 mypackage/__init__.py + mypackage/submod/worker.py，必须满足两个条件才能跑通：
- 终端当前目录是
mypackage的父目录（即包含mypackage/的那层） - 执行命令为
python -m mypackage.submod.worker，不是python mypackage/submod/worker.py
如果当前目录不对，python -m 也会报 ImportError: No module named 'mypackage' —— 它不猜路径，只查 sys.path。
__init__.py 缺失或位置错误会导致包层级断裂
相对导入依赖明确的包嵌套关系。例如你写了 from ..model import config，Python 就会尝试从当前模块所在包向上跨两级找 model。但如果项目结构是：
draft/
├── model/
│ └── __init__.py
└── package/
└── __init__.py
那么 draft/package/b.py 里用 from ..model import config 一定失败：因为 draft/ 没有 __init__.py，Python 把 model 和 package 都视为同级顶层包，..model 就等于“跳出顶层”，自然被禁止。
修复方式只有两种：
- 在
draft/__init__.py补上（让整个目录成为包） - 或者重构为单根结构，如
src/model/和src/package/，再统一用python -m src.package.b
手动补 __package__ 是权宜之计，不是解法
有人在脚本开头加这段代码来绕过报错：
if __name__ == '__main__' and __package__ is None:
import os, sys
parent_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, parent_dir)
__package__ = 'src.module'
它确实能让 python src/module/runner.py 跑起来，但问题没解决，只是掩盖了结构缺陷：
- 一旦模块被其他包以绝对路径导入，这段逻辑会重复执行或冲突
- CI/CD 环境中
sys.path可能被重置，行为不可控 - 多人协作时，没人知道该脚本到底属于哪个包、依赖哪一层
真正该检查的是：这个文件是否真的需要被直接执行？如果答案是“是”，那它就不该用相对导入；如果答案是“否”，那就删掉 if __name__ == '__main__'，另起一个干净的入口文件（如 main.py），用绝对导入调用它。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
