ImportError: cannot import name 本质是导入时序问题而非路径问题，主因是循环引用或顶层依赖未初始化，需用python -v定位回环、将导入移入函数、拆分共享模块或用TYPE_CHECKING注解解决。
为什么 ImportError: cannot import name 常不是路径问题，而是导入时序问题
这个错误表面看像模块没找到，但绝大多数情况实际是 Python 在解析模块时遇到了未定义的名称——尤其当两个模块互相 import，或在模块顶层执行了依赖尚未初始化完成的对象访问时。Python 的 import 是运行时行为，不是编译期绑定，所以 from A import X 要求 A.py 已完整执行到定义 X 的那一行。
常见诱因包括：
-
A.py顶部from B import func，而B.py又在顶部from A import cls，形成循环引用 -
B.py中有from A import CONST，但A.py里CONST = some_func()依赖了还没加载的B - 使用了
if TYPE_CHECKING:却忘了把真正运行时需要的导入移出该块
如何快速定位循环引用：用 python -v 看导入链
在终端中加 -v 参数运行脚本，Python 会打印所有 import 尝试和成功/失败细节，能直接看到卡在哪一步：
python -v myscript.py
重点关注输出中连续出现的 importing A → importing B → importing A 这类回环，以及紧随其后的 AttributeError 或 NameError。注意：-v 输出极长，建议配合 grep -A5 -B5 "A\|B" 过滤。
立即学习“Python免费学习笔记（深入）”；
另一个轻量办法是临时在疑似模块开头加日志：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
print("[A.py] starting")<br>from B import something<br>print("[A.py] imported from B")如果只看到第一个 print 就报错，说明问题就出在那行 import 上。
修复循环引用的三种实操方式（按推荐顺序）
不要强行删掉一个 import，要根据依赖本质选择解法：
-
把导入移到函数内部：如果只是某个函数需要对方模块，把它从模块顶层挪进去。这样只有调用时才触发导入，避开初始化阶段冲突。
def process():<br> from B import helper # ✅ 延迟到运行时<br> return helper()
-
拆分接口与实现：把共用的类型、常量、协议抽到第三个模块（如
types.py或shared.py），A 和 B 都只导入它，不互导。 -
用字符串注解 +
TYPE_CHECKING：仅用于类型提示的导入，必须包在if TYPE_CHECKING:下，并确保运行时逻辑不依赖它：from typing import TYPE_CHECKING<br>if TYPE_CHECKING:<br> from B import SomeClass<br><br>def foo(x: "SomeClass") -> None: ... # ✅ 字符串避免运行时导入
sys.path 和 __init__.py 并非万能，但容易被误判为根因
当确认不是循环引用后，再排查路径问题。重点检查：
- 当前工作目录是否意外影响了
sys.path[0]（即“.”）？用print('\n'.join(sys.path))确认顺序 - 包结构里漏了
__init__.py（哪怕空文件），会导致子目录不被视为包，from pkg.sub import mod失败 - 安装了同名第三方包（比如你写了
requests.py），Python 优先导入它而非pip install的requests库
临时修改 sys.path 是调试手段，不是解决方案；用 pip install -e . 安装本地包，比手动改路径更可靠。
真正难缠的 case 往往是循环引用藏在间接依赖里：A → B → C → A。这时候单看 A 和 B 没问题，得顺着 import 链一路 grep "import" 才能找到闭环点。
