如何正确处理 Python 包内模块的相对导入问题-Python教程-PHP中文网

如何正确处理 Python 包内模块的相对导入问题

当主程序通过子包调用内部模块时，因 Python 模块搜索路径未包含配置文件所在目录，导致 ModuleNotFoundError。本文详解两种可靠解法：使用相对导入或配置 PYTHONPATH，并提供可直接复用的代码示例与最佳实践建议。

当主程序通过子包调用内部模块时，因 python 模块搜索路径未包含配置文件所在目录，导致 `modulenotfounderror`。本文详解两种可靠解法：使用相对导入或配置 `pythonpath`，并提供可直接复用的代码示例与最佳实践建议。

在 Python 项目中，将敏感信息（如 API 密钥）抽离到独立模块（如 api_keys.py）是安全开发的重要实践。但若目录结构设计不当或导入方式不匹配执行上下文，极易触发 ModuleNotFoundError: No module named 'api_keys' —— 这并非代码逻辑错误，而是 Python 解释器模块解析机制与当前工作目录/执行入口共同作用的结果。

根据您提供的项目结构：

.
├── main.py
└── apis/
    ├── __init__.py
    ├── api_keys.py
    └── coordinates_api.py

api_keys.py 与 coordinates_api.py 同属 apis 包，但 coordinates_api.py 中使用 import api_keys 是绝对导入，它要求 api_keys 必须是顶层可导入模块（即位于 sys.path 中的某个路径下），而实际它仅存在于 apis/ 子目录中。因此，当 main.py 作为入口运行时，Python 不会自动将 apis/ 加入模块搜索路径，导致失败。

✅ 推荐方案一：使用显式相对导入（最符合 PEP 8 与包规范）
修改 apis/coordinates_api.py 中的导入语句：

import requests
from . import api_keys  # ✅ 相对导入：从当前包（apis）导入 api_keys

class CoordinatesAPI:
    def __init__(self, api_key=None):
        self.api_key = api_keys.geo  # 保持不变
    # ... 其余代码不变

同时，确保 apis/__init__.py 存在（即使为空），这是 Python 将 apis/ 视为包的必要条件。此方式清晰表达了模块间的层级关系，且不依赖运行位置，是现代 Python 包开发的标准做法。

⚠️ 注意：相对导入仅在模块作为包的一部分被导入时有效（即不能直接运行 python apis/coordinates_api.py）。若需单独测试该模块，应使用 -m 参数：

python -m apis.coordinates_api  # ✅ 正确：以模块方式运行

✅ 备选方案二：通过 PYTHONPATH 扩展模块搜索路径
若因历史原因必须保留 import api_keys 形式，可在运行前将 apis/ 父目录加入 PYTHONPATH：

Linux/macOS：

python-script-generator
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。

下载
```
export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"
python main.py
```

Windows（PowerShell）：

$env:PYTHONPATH = "$env:PYTHONPATH;C:\path\to\your\project"
python main.py

? 原理：PYTHONPATH 会追加到 sys.path 开头，使解释器能在指定目录下查找到 api_keys.py。但该方式依赖环境配置，不利于团队协作与 CI/CD，仅建议临时调试使用。

? 额外加固建议：

在 api_keys.py 中添加 __all__ = ['geo'] 显式导出变量，避免意外导入其他内容；
将 api_keys.py 重命名为 api_keys.py.example 并加入 .gitignore，配合 README 提供配置模板，彻底规避密钥泄露风险；
使用 python -m site 验证当前 sys.path，快速定位路径问题。

综上，优先采用相对导入（from . import api_keys） —— 它语义明确、可移植性强、无需环境变量干预，是解决此类跨模块导入问题最稳健、最符合 Python 生态的设计选择。