本文详解如何在 Python 项目中从与当前脚本处于同一层级（平行）的其他子目录中可靠导入模块，重点解决 ImportError: attempted relative import with no known parent package 错误，并提供基于绝对导入和正确执行方式的生产级解决方案。
本文详解如何在 python 项目中从与当前脚本处于同一层级（平行）的其他子目录中可靠导入模块，重点解决 `importerror: attempted relative import with no known parent package` 错误，并提供基于绝对导入和正确执行方式的生产级解决方案。
在 Python 项目结构中，当模块分布在多个同级子目录下（如 subfolder1/my_prog.py 需要导入 subfolder2/credentials.py），直接使用相对导入（如 from ..subfolder2 import credentials）会失败——这不是路径配置问题，而是 Python 导入机制的本质限制：相对导入依赖包上下文，而直接运行脚本（python my_prog.py）会使该文件被视为顶层脚本（__main__），不构成任何包的一部分，因此 .. 无意义。
✅ 正确做法：以包方式运行 + 绝对导入
首先，确保项目具备标准包结构（含 __init__.py 文件）：
project_folder/
├── __init__.py # 必须存在，标识 project_folder 为根包
├── subfolder1/
│ ├── __init__.py # 可为空，但建议保留
│ └── my_prog.py
└── subfolder2/
├── __init__.py
└── credentials.py? 注意：__init__.py 文件可为空，但必须存在（Python 3.3+ 支持隐式命名空间包，但显式声明更稳定、兼容性更好）。
接着，在 my_prog.py 中使用绝对导入（而非相对导入）：
立即学习“Python免费学习笔记（深入）”；
# subfolder1/my_prog.py from subfolder2 import credentials print(credentials.api_key) # 输出: supersecretapikey
然后，关键一步：不要直接运行脚本文件，而是从项目根目录（project_folder）以模块方式执行：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
cd project_folder python -m subfolder1.my_prog
此时，Python 将 project_folder 视为顶级包，subfolder1 和 subfolder2 均为其子包，from subfolder2 import credentials 可被正确解析。
❌ 常见错误及原因
- python subfolder1/my_prog.py → 失败：my_prog.py 成为 __main__，无父包，所有相对/绝对跨包导入均失效。
- from ..subfolder2 import credentials → 失败：.. 要求当前模块属于某个包（即必须通过 -m 运行），且上级包需可识别；单独脚本不满足条件。
- 仅加 __init__.py 但仍用 python xxx.py 运行 → 无效：__init__.py 不改变执行模式，只影响包识别。
? 进阶建议：提升健壮性与可维护性
避免硬编码路径或修改 sys.path：虽然 sys.path.insert(0, '..') 等方式能临时绕过，但破坏封装性、易引发冲突，不推荐用于生产环境。
-
使用 pyproject.toml 配置可选入口点（现代 Python 项目）：
# pyproject.toml [project] name = "my_project" requires-python = ">=3.12" [project.entry-points."console_scripts"] run-prog = "subfolder1.my_prog:main" # 假设 my_prog.py 定义了 main() 函数
安装后可通过 my_project-run-prog 命令调用，自动支持包内导入。
敏感信息管理提示：credentials.py 直接暴露 API Key 存在安全风险。建议改用 python-dotenv 加载 .env 文件，或结合 os.getenv() 与远程密钥管理服务（如 AWS Secrets Manager）。
总之，Python 的模块导入遵循明确的“执行上下文”规则。掌握 python -m
