如何在 Python 中从并行子目录正确导入模块-Python教程-PHP中文网

本文详解 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+ 需要开启：辅助功能 + 屏幕录制权限

下载

❌ 常见错误与规避

错误做法：在 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