python 禁止在非包内脚本中使用相对导入，核心目的是强制开发者遵循标准化的项目结构——将多文件项目封装为可安装的 python 包，从而统一模块解析逻辑、提升可移植性与可维护性。
python 禁止在非包内脚本中使用相对导入，核心目的是强制开发者遵循标准化的项目结构——将多文件项目封装为可安装的 python 包，从而统一模块解析逻辑、提升可移植性与可维护性。
相对导入（如 from ..modules import module1）在 Python 中被明确限定于已声明为包的命名空间内，即必须满足两个前提：
- 当前模块位于一个含
__init__.py（或 PEP 420 隐式包）的目录中； - 该模块是通过
import语句（而非直接执行）被加载的——换言之，它必须作为包的一部分被导入，而非以python script1.py方式直接运行。
这并非技术限制，而是经过深思熟虑的设计决策。Python 解释器需要明确的“包上下文”来解析 .. 这类上级引用：当脚本被直接执行时，__name__ 为 '__main__'，__package__ 为 None，解释器无法推断其在模块层级中的位置，因此拒绝解析任何相对路径，避免歧义和不可预测的行为。
你遇到的典型结构：
my_project/
├── modules/
│ ├── __init__.py
│ ├── module1.py
│ └── module2.py
└── scripts/
├── script1.py
└── script2.py看似合理，但 scripts/script1.py 直接运行时，Python 将其视为顶层脚本，不构成包的一部分，故 from ..modules import module1 必然报错 SystemError: Parent module '' not loaded, cannot perform relative import。
立即学习“Python免费学习笔记（深入）”；
✅ 正确解法不是绕过规则，而是拥抱 Python 的标准分发模型：
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
第一步：重构为合规包结构
推荐采用现代 pyproject.toml 驱动的布局：
my_project/ ├── pyproject.toml # 声明元数据与入口点 ├── src/ │ └── my_project/ # 实际包根目录（推荐隔离源码） │ ├── __init__.py │ ├── modules/ │ │ ├── __init__.py │ │ ├── module1.py │ │ └── module2.py │ └── scripts/ │ ├── __init__.py │ ├── script1.py # 可含 def main(): ... │ └── script2.py
第二步：在 pyproject.toml 中声明命令行入口
[project] name = "my-project" version = "0.1.0" [project.scripts] script1 = "my_project.scripts.script1:main" script2 = "my_project.scripts.script2:main"
第三步：本地安装并运行
pip install -e . # 开发模式安装（符号链接，实时生效） script1 # 自动调用 my_project/scripts/script1.py 中的 main()
此时 script1.py 内部可安全使用绝对导入（如 from my_project.modules import module1），也可在包内模块间使用相对导入（如 from ..modules import module1），且所有环境行为一致。
⚠️ 注意事项：
- 避免
sys.path.append(...)类 hack：它破坏可重现性，导致 IDE 无法正确索引、测试工具失效、CI 环境行为不一致； - 不要将
scripts/放在包外又试图用-m运行（如python -m scripts.script1）：若scripts无__init__.py或未在PYTHONPATH中，仍会失败； - 使用
src/目录是行业最佳实践，可防止意外将当前目录当作包导入（import my_project错误指向项目根而非src/my_project）。
总结而言，Python 用“禁止相对导入”这一刚性约束，引导开发者从项目初期就采用可安装、可测试、可分发的标准包结构。短期学习成本换来的是长期的协作效率、环境一致性与工具链兼容性——这不是限制，而是 Python 生态可持续演进的关键设计哲学。
