本文详解 Python 项目中跨并行子目录（如 subfolder1 和 subfolder2）进行模块导入的规范方法，重点解决 ImportError: attempted relative import with no known parent package 错误，涵盖运行方式、目录结构、__init__.py 作用及绝对导入最佳实践。
本文详解 python 项目中跨并行子目录（如 `subfolder1` 和 `subfolder2`）进行模块导入的规范方法，重点解决 `importerror: attempted relative import with no known parent package` 错误，涵盖运行方式、目录结构、`__init__.py` 作用及绝对导入最佳实践。
在 Python 中，模块导入路径始终以当前执行上下文（即 Python 解释器启动时的工作目录）为基准，而非被导入文件自身的物理位置。这是理解并行目录导入问题的核心前提。当你直接运行 python subfolder1/my_prog.py 时，Python 将 subfolder1 视为顶层包，此时 from ..subfolder2 import credentials 中的 .. 意味着“上一级包”，但 subfolder1 并未被识别为某个已知包的子模块（即缺少父包上下文），因此触发 ImportError: attempted relative import with no known parent package。
✅ 正确做法是：将项目根目录设为 Python 包根，并使用 -m 方式运行模块。请按以下结构组织项目（确保所有子目录含空的 __init__.py 文件，显式声明为包）：
project_folder/
├── __init__.py # 必须存在，使 project_folder 成为可导入包
├── subfolder1/
│ ├── __init__.py
│ └── my_prog.py
└── subfolder2/
├── __init__.py
└── credentials.py在 my_prog.py 中，使用绝对导入（推荐）或包内相对导入：
# ✅ 推荐：绝对导入（清晰、健壮、无路径依赖） from subfolder2 import credentials # 或 ✅ 合法的包内相对导入（需配合 -m 运行） from ..subfolder2 import credentials # 注意：仅在作为子模块运行时有效
然后，在 project_folder/ 目录下执行：
立即学习“Python免费学习笔记（深入）”；
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
cd project_folder python -m subfolder1.my_prog
⚠️ 关键说明：
- python -m subfolder1.my_prog 告诉 Python：以 project_folder 为包根，将 subfolder1.my_prog 当作一个模块来执行（而非普通脚本），此时 subfolder1 和 subfolder2 同属 project_folder 的子包，绝对导入 from subfolder2 import credentials 完全合法；
- 直接 python subfolder1/my_prog.py 绕过了包机制，Python 不会自动将父目录加入 sys.path，任何涉及上级或同级目录的导入都会失败；
- __init__.py 文件虽在 Python 3.3+ 后非强制（PEP 420 隐式命名空间包），但显式添加仍是最兼容、最明确的做法，尤其在部署到远程服务器等生产环境时。
? 最佳实践总结：
- 始终优先使用绝对导入（如 from subfolder2 import credentials），避免相对导入的上下文陷阱；
- 项目入口点应通过 python -m package.module 启动，而非直接执行 .py 文件；
- 确保项目根目录可被 Python 识别为包（含 __init__.py）；
- 若需动态调整模块搜索路径（不推荐用于常规项目），可在代码开头临时追加：
import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent)) # 将 project_folder 加入路径 from subfolder2 import credentials
但该方式破坏可移植性与可维护性，应仅作调试或特殊场景备用。
遵循以上规范，即可在本地开发与远程服务器上稳定实现跨并行子目录的模块导入。
