Python循环导入在运行时暴露，因模块按序加载导致部分初始化失败；定位需用最小复现验证，解法包括函数内导入、拆分公共模块或字符串类型注解。
Python 循环导入（Circular Import）通常不会在代码写完就立刻报错，而是在运行时、尤其是模块被实际导入或使用时才暴露，比如 ImportError: cannot import name 'X' from partially initialized module。定位和解决的关键在于理解 Python 的导入机制：模块是按执行顺序逐行加载的，若 A 导入 B，B 又在定义完成前试图导入 A 中尚未初始化完毕的对象，就会出问题。
看导入语句的执行时机
不是所有 import 都会在模块顶层立即触发完整加载：
- 顶层 import（模块开头）：会立即尝试加载并执行目标模块，最容易引发循环
- 函数/方法内部的 import：只在调用时才执行，可延后加载，常用于打破循环
-
from ... import ... 在顶层：不仅导入模块，还尝试获取具体名字，对初始化状态更敏感，比
import module更容易失败
用最小复现快速验证怀疑点
不要直接在大型项目里排查。新建两个空文件模拟疑似循环链：
# a.py
print("a.py loading")
from b import func_b
def func_a(): return "A"
print("a.py loaded")
立即学习“Python免费学习笔记（深入）”；
# b.py
print("b.py loading")
from a import func_a # ← 这里会卡住，因为 a.py 还没执行完
def func_b(): return "B"
print("b.py loaded")
运行 python a.py，观察输出顺序和报错位置，就能确认是否为循环及断点在哪一行。
常用解法：按场景选一种
① 把 import 移到函数内（最轻量）
适用于仅在特定逻辑中需要对方模块功能的情况：
# b.py
def func_b():
from a import func_a # 延迟到调用时才导入
return func_a() + " from B"
② 拆分公共内容到第三个模块
当 A 和 B 都依赖同一组类、配置或工具函数时，把它们抽到 common.py 或 utils.py，让 A 和 B 都只单向导入它。
③ 使用字符串标注类型（仅限 type hint）
如果循环只出现在类型注解中（如 def f(x: A) -> B:），用字符串代替真实引用，并在顶部加 from __future__ import annotations，Python 3.7+ 支持，类型检查器仍能识别，运行时不执行导入。
调试技巧：临时加 print 和 sys.modules 检查
在可疑模块开头插入：
import sys
print(f"[{__name__}] sys.modules keys: {list(sys.modules.keys())[:5]}...")
观察导入过程中 sys.modules 是否已存在但值为 None（表示正在初始化中），这是循环导入的典型信号。也可以在报错后进入 pdb，检查 sys.modules['module_name'] 的值。
