Python导入机制困惑：企业开发中相对导入问题排查

核心问题根源 #

1. 直接运行脚本时相对导入失效的原因 #

当你执行python package/moduleA.py时，Python会把package/目录加入sys.path，并将moduleA.py当作顶层脚本（__name__为__main__），而非package包的一部分。此时相对导入（以.开头）依赖的“父包上下文”不存在，Python无法识别moduleA属于package，因此抛出ImportError: attempted relative import with no known parent package。

2. 移到src目录后导入正常的原因 #

将moduleA.py移到src/下后，运行python moduleA.py时，src/会被加入sys.path。此时package/是src/下的合法Python包，你可以通过绝对导入from package.subpackage2 import moduleZ找到模块——本质是绕开了相对导入的上下文依赖，直接从顶层包路径导入。

3. -m参数运行错误的原因 #

使用-m参数时，必须指定模块的点分路径而非文件路径，且要保证包所在的目录在sys.path中。正确的操作是：

• 进入src/目录
• 执行python -m package.moduleA

你之前尝试的python -m package/moduleA.py或package/moduleA都是错误用法：-m后不能带.py后缀，也不能用文件路径的斜杠，必须用模块层级的点分隔符。

4. 测试与应用运行的差异 #

测试框架（如pytest）默认会将项目根目录（src/）加入sys.path，并且会把测试相关的模块当作包的一部分加载（moduleA的__name__会是package.moduleA）。此时相对导入的上下文存在，所以from .subpackage2 import moduleZ能正常工作。但应用运行时直接执行脚本，没有包上下文，导致相对导入失效。

解决方案 #

方案1：以模块方式运行应用 #

始终进入src/目录，执行：

python -m package.moduleA

这种方式会让Python将package当作合法包加载，保留相对导入的上下文。

方案2：改用绝对导入 #

将moduleA.py中的导入语句改为：

from package.subpackage2 import moduleZ

同时确保src/目录在sys.path中——可以通过以下方式实现：

• 运行脚本前设置环境变量：export PYTHONPATH=/path/to/your/src（Linux/macOS）或set PYTHONPATH=C:\path\to\your\src（Windows）
• 在moduleA.py开头添加代码手动加入路径：

  import sys
  from pathlib import Path
  # 将src目录加入sys.path
  sys.path.append(str(Path(__file__).parent.parent))
  

方案3：安装为可编辑包 #

在src/目录下执行：

pip install -e .

这会将package安装为全局可导入的包，不管在哪里运行脚本，绝对导入和相对导入都能正常工作，适合团队开发场景。

内容的提问来源于stack exchange，提问作者daze-hash