本文详解 Python 项目中跨并行子目录（如 subfolder1 → subfolder2）进行模块导入的原理与实践方案，涵盖相对导入失败原因、推荐的绝对导入方式、-m 运行模式用法，并提供可直接复用的结构化示例与关键注意事项。
本文详解 python 项目中跨并行子目录（如 `subfolder1` → `subfolder2`）进行模块导入的原理与实践方案，涵盖相对导入失败原因、推荐的绝对导入方式、`-m` 运行模式用法，并提供可直接复用的结构化示例与关键注意事项。
在 Python 项目开发中，当模块分布在并行子目录下（例如 subfolder1/my_prog.py 需导入 subfolder2/credentials.py），直接使用 from ..subfolder2 import credentials 会触发 ImportError: attempted relative import with no known parent package 错误。这并非路径配置或 __init__.py 缺失所致，而是源于 Python 导入机制的核心设计：相对导入始终以“当前执行入口的父包”为基准，而非被导入文件所在位置。当你在 subfolder1/ 下执行 python my_prog.py，Python 将 my_prog.py 视为顶层脚本（__name__ == '__main__'），不归属于任何包，因此 .. 无意义。
✅ 正确且推荐的解决方案是采用 绝对导入 + -m 模块运行模式，确保 Python 将整个项目根目录识别为包上下文：
✅ 步骤一：规范项目结构（含必要 __init__.py）
project_folder/
├── __init__.py # 标记 project_folder 为包根
├── subfolder1/
│ ├── __init__.py # 可选，但建议添加
│ └── my_prog.py
└── subfolder2/
├── __init__.py # 可选，但建议添加
└── credentials.py? 注意：__init__.py 文件可为空，但必须存在（即使为空文件），否则 Python 不识别对应目录为包。
✅ 步骤二：在 my_prog.py 中使用绝对导入
# subfolder1/my_prog.py
from subfolder2 import credentials # ✅ 绝对导入：基于 project_folder 根目录
print("API Key:", credentials.api_key)✅ 步骤三：从项目根目录运行（关键！）
cd project_folder python -m subfolder1.my_prog
? python -m subfolder1.my_prog 告诉 Python：将 subfolder1.my_prog 作为模块启动，此时 project_folder 自动成为包根，subfolder2 可被直接解析为顶层子包。
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac下载让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
立即学习“Python免费学习笔记（深入）”；
❌ 常见错误与规避
- 错误做法：在 subfolder1/ 内执行 python my_prog.py → 导致相对/绝对导入均失效（脚本脱离包上下文）。
- 不推荐做法：动态修改 sys.path 或手动添加 project_folder 到 PYTHONPATH → 破坏可移植性，违反 Python 包管理最佳实践。
- 环境变量依赖：如题所述需部署至远程服务器，硬编码路径或依赖环境变量将显著增加运维复杂度，应避免。
? 补充：若必须保留脚本式执行（python my_prog.py）
可在 my_prog.py 开头注入项目根路径（仅限开发调试，生产环境慎用）：
# subfolder1/my_prog.py（不推荐用于生产） import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent)) # 将 project_folder 加入路径 from subfolder2 import credentials
✅ 总结：最佳实践清单
- ✅ 始终在项目根目录下使用 python -m package.module 运行；
- ✅ 所有子目录添加空 __init__.py 文件；
- ✅ 在代码中统一使用绝对导入（from subfolder2 import xxx）；
- ✅ 避免 .. 相对导入，除非明确处于嵌套包内且通过 -m 启动；
- ✅ 远程部署时，确保目录结构与本地一致，无需额外环境变量配置。
遵循以上原则，即可实现清晰、可维护、跨平台兼容的并行目录模块导入。
