根本原因是Python模块顶层导入时同步执行导致部分初始化，A未完成即被B引用，引发ImportError或AttributeError；解法包括推迟导入、拆分公共模块、字符串类型提示配合TYPE_CHECKING。
模块循环导入时为什么报 ImportError 或 AttributeError
根本原因是 Python 在执行 import 语句时会同步加载并执行模块顶层代码。当 A 模块在顶层 import B，B 又在顶层 import A，Python 还没把 A 完全初始化完就回头找 A 的属性，此时 A 的命名空间是空的或不完整，于是抛出 ImportError: cannot import name 'X' from partially initialized module 'A'，或者后续调用时触发 AttributeError。
推迟导入：把 import 移到函数/方法内部
这是最常用且低侵入的解法——避开顶层执行时机，等真正需要时再加载。适用于工具函数、非启动逻辑、按需使用的类或配置。
例如：
# a.py
def get_user():
from b import User # ✅ 延迟到调用时才导入
return User("alice")
<h1>b.py</h1><p>def create_profile():
from a import get_user # ✅ 同样延迟
user = get_user()
return f"Profile for {user.name}"
- 仅在函数体、方法体、条件分支内做
import，不要放在类定义或模块顶层 - 注意：多次调用会重复导入（CPython 有缓存，实际开销小），但模块初始化代码仍只执行一次
- 不能用于类型提示（
from __future__ import annotations可缓解）或继承父类（因 class 语句需静态解析）
重构为独立模块：拆出公共依赖
当 A 和 B 相互依赖的是某些共享数据、常量或基础类时，说明它们本就不该紧耦合。把共用部分抽成 common.py 或 models.py，让 A 和 B 都单向依赖它。
立即学习“Python免费学习笔记（深入）”；
例如：
# models.py
class BaseUser:
def __init__(self, name): self.name = name
<h1>a.py</h1><p>from models import BaseUser
class Admin(BaseUser):
pass</p><h1>b.py</h1><p>from models import BaseUser
def validate(user: BaseUser):
return isinstance(user, BaseUser)
- 抽离后，A 和 B 不再直接引用彼此，循环打破
- 适合领域模型、DTO、配置常量、工具函数等稳定内容
- 注意避免把临时逻辑也塞进公共模块，否则会演变成“上帝模块”
使用字符串类型提示 + typing.TYPE_CHECKING
类型检查阶段需要引用，但运行时不需加载——用条件导入配合类型注解可彻底解耦。
例如：
# a.py
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from b import UserProfile # ✅ 仅 mypy 看得见，运行时跳过
<p>def process(user: "UserProfile") -> str: # 字符串注解绕过运行时解析
return f"Handling {user.name}"
- 必须搭配
from __future__ import annotations（Python 3.7+）才能安全使用字符串注解 -
TYPE_CHECKING是 typing 模块的常量，值为False，但 mypy/pyright 会将其视为True - 不能用于运行时反射（如
isinstance(obj, UserProfile)），只能用于类型提示
循环导入不是语法错误，而是模块初始化顺序与依赖表达不匹配的结果。最容易被忽略的是：你以为只是“换个位置 import 就行”，却没意识到类继承、装饰器、模块级变量赋值这些操作都发生在顶层，只要出现在 import 链上，就可能触发半初始化状态。动手前先画两笔依赖图，比硬调十分钟更省时间。
