30.8 导入路径与循环导入坑点

Python 的导入系统在小型脚本里表现良好，但项目结构一复杂，就会暴露出两个高频坑：导入路径混乱和循环导入。这两个问题会导致代码无法运行，而且报错信息往往不直观。

导入路径的坑

Python 解释器在 import 时，会按顺序搜索 sys.path 中的目录。这个列表包含脚本所在目录、环境变量 PYTHONPATH 中的路径、标准库目录以及第三方包安装位置。坑点大多源于对搜索路径的“想当然”。

典型错误 1：直接运行包内模块时，相对导入失败

假设你有这样一个结构：

project/
├── mypkg/
│   ├── __init__.py
│   ├── a.py
│   └── b.py
└── main.py

a.py 想导入同包的 b 模块，写了 from . import b 这样的相对导入。如果你直接在命令行执行 python mypkg/a.py，会抛出一串“ImportError: attempted relative import with no known parent package”。原因是直接运行时，Python 把 a.py 当作顶级模块，不知道它属于 mypkg 包，相对导入的“点”找不到父包。

解决方案：永远不要直接运行包内模块作为脚本；改用 python -m mypkg.a 从项目根目录启动，让 Python 正确识别包结构。或者通过顶层 main.py 导入 mypkg 的模块再调用其功能。

典型错误 2：把项目根目录添加到 sys.path 的方式不一致

在很多项目里，常见一种“肮脏”技巧：在某个模块开头写：

import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent.parent))

这种做法的问题在于：

每个开发者插入的路径可能不同，导致不同机器上导入行为不一致。
如果多个模块都这样“暴力修路”，会污染全局导入路径，造成模块命名冲突，且极难排查。

正确做法：使用虚拟环境，并通过 pip install -e .（以 editable 模式安装当前项目）让项目成为一个可导入的包，这样无需手动修改 sys.path。如果必须用脚本，只应在入口脚本（而非每个模块）中统一处理路径。

循环导入的坑

循环导入是指两个模块相互导入对方：模块 A 导入模块 B，而模块 B 在初始化过程中又试图导入模块 A。这通常不会直接报“循环导入”的错误，而是表现为某个名称尚未被定义，或者导入结果为 None。

典型场景：

# a.py
from b import func_b

def func_a():
    print("A")

# b.py
from a import func_a

def func_b():
    func_a()

执行 a.py 时：Python 开始执行 a.py，遇到 from b import func_b 时暂停 a.py 去加载 b.py；b.py 刚开始执行，又遇到 from a import func_a，此时 a.py 还在初始化中，尚未定义 func_a，于是 func_a 的导入会失败，抛出 ImportError 或 NameError。

更隐蔽的情况是：导入成功，但获取到的是 None。这是因为 Python 的模块缓存机制：sys.modules 中先插入一个空的模块对象，然后执行模块代码。当 b.py 导入 a 时，得到的只是那个尚未执行完的 a 模块对象，里面的变量还未赋值。

解决方案：

延迟导入：将导入语句挪到函数或方法内部，而不是放在模块顶部。这样导入只会在调用时发生，此时双方都已完全加载。

  # a.py
  def func_a():
      from b import func_b  # 在函数内导入
      func_b()

重组设计：如果两个模块相互依赖太紧，大概率是职责划分有问题。可以考虑提取共同依赖的接口或数据到一个独立模块 common.py 中，让双方都依赖于它。
导入整个模块而非具体名称：使用 import b 代替 from b import func_b，然后通过 b.func_b() 访问。这样只要求 b 模块对象存在，不要求其内部名字在导入时刻就定义好。
使用 init.py 统一管理：在包的 init.py 中控制导入顺序，避免模块间在初始化阶段就互相调用。

排查技巧：遇到奇怪的“模块没有属性 X”且确认 X 存在于文件中时，可以检查 print(sys.modules['模块名'].dict.keys()) 查看实际加载了哪些名字，多数情况就是因为循环依赖导致模块初始化不完全。

总之，保持导入链的清晰单向性是预防循环导入的根本。导入路径问题则要遵循“用包代替路径拼接，用安装代替手动改 sys.path”的原则。这两点坚持好，就能避开 90% 的导入坑。