1. 问题全貌：循环导入到底长什么样
先花两分钟把循环导入这件事说透。很多同学第一次踩到“两个Python文件相互import”这个坑，是从一句报错开始的：
ImportError: cannot import name 'xxx' from partially initialized module 'yyy' (most likely due to a circular import)英文报错里那个partially initialized module非常关键，意思是“模块只初始化了一半”。为什么只初始化了一半？因为程序在执行import语句的时候，两个文件正在互相等对方加载完，结果谁也没法继续走，卡死在半路上。
我见过最典型的场景是这样的：某个业务系统里有一个order.py（订单模块）和一个customer.py（客户模块），订单要查客户信息，客户要看订单记录，两边一拍即合，互相 import。刚开始代码少，能跑；等代码量一大，某次改动之后突然就炸了。这个场景几乎是所有业务系统都会遇到的通病，不是某个人代码写得差，而是模块划分一开始就没把依赖关系理清楚。
需要先说明的是，循环导入本身并不总是致命错误。Python 解释器允许两个模块互相引用的前提是：至少有一方在import的时候不需要立刻用到对方的全部内容。真正出问题的地方，在于“import 的时机”和“使用被导入内容的时机”冲突了。
2. 为什么两个文件互相 import 会触发这个坑
2.1 Python 模块的执行机制，简单版
要理解循环导入，必须先搞清楚 Python 处理import语句的原理。很多人因为在别的语言里习惯了一整套 import 机制，对 Python 的这套逻辑反而没仔细想过。
当我们执行import order的时候，Python 解释器大致做这样几件事：
- 检查
sys.modules这个字典，看order是不是已经被加载过。如果加载过，直接取缓存，不再重复执行模块代码。 - 如果没加载过，解释器去磁盘上找到
order.py这个文件，把它编译成字节码，然后从头到尾逐行执行这个文件里的代码。 - 执行完毕，把模块对象放进
sys.modules里，这样后续再有人 import 就直接取缓存。
这里需要注意一个细节：模块对象是在sys.modules里先注册的，还是等代码全部执行完才注册的？答案是——Python 在开始执行模块代码之前，就会先在sys.modules里放一个“空壳模块对象”，然后再逐行执行模块内容。这么做的目的，是为了处理模块内部互相引用的情况。
但如果这个“空壳模块对象”被另一个模块在关键时刻拿到了，问题就来了。
2.2 循环导入的触发链路图解
举一个具体例子，我重新构造一个最小复现结构：
# a.py from b import B class A: def __init__(self): self.b = B()# b.py from a import A class B: def __init__(self): self.a = A()执行python a.py的时候，实际发生了什么：
- 解释器开始执行
a.py，把a模块的“空壳对象”放进sys.modules。 - 执行到
from b import B，发现b还没有加载，于是转去执行b.py。 - 解释器把
b模块的空壳对象放进sys.modules，开始执行b.py。 b.py第一行是from a import A，这时sys.modules里已经有a了，但它是个空壳，里面还没有A这个类。- 于是 Python 报错：
cannot import name 'A' from partially initialized module 'a'。
看到这里你应该明白了：问题不是“不能循环导入”，而是“循环导入时，对方模块恰好还没有执行到定义你要的那个名字的那一行”。
打个比方。你早上发消息给室友说“出门前把门锁了”，室友回你“你把钥匙带好”，结果两个人都在等对方先做完自己的动作，谁也没法先出门。循环导入就是这种互相等待的局面。
2.3 三种 import 写法的影响差异
循环导入踩坑之后，很多人第一反应是：“我换一种 import 写法不就好了？”这个想法方向是对的，但只对了一部分。我来拆一下三种常见写法在循环导入场景下的区别。
import a # 第一种：直接导入模块 from a import A # 第二种：从模块里导入某个名字 from a import A as A_type # 第三种：带别名的从模块导入第一种写法的特点：只要模块对象在sys.modules里存在，import a就能成功，哪怕它是个空壳。所以你后续使用a.A的时候才可能报错AttributeError: module 'a' has no attribute 'A'，因为此时模块还没执行到定义A的那一行。
第二种写法就狠多了：它不仅是拿模块对象，还要立刻从模块的全局命名空间里取出A这个名字。如果模块只初始化到一半，A根本不存在，当场ImportError。
第三种写法的机制和第二种一样，只是多了个别名，该报错还是会报错。
所以实际经验是：在某些循环导入场景下，把from x import y改成import x，然后代码里统一用x.y来访问，确实能绕过去。但要注意，这只是“绕过去”，不是“解决”了循环依赖本身。如果你的a模块在空壳状态下被b拿到，之后b在模块顶层就去调用a.A，照样炸。
3. 常规解法一：延迟导入
3.1 什么是延迟导入，怎么用
延迟导入是应对循环导入最直接、最低成本的手段。核心思路很简单：把import语句从模块顶层移动到真正使用它的函数或方法里面去。
还是上面那个例子，改造b.py：
# b.py class B: def __init__(self): from a import A self.a = A()这样改完之后，from a import A不再在模块加载阶段执行，而是在B的构造函数执行期间才触发。绝大多数时候，这个方法能直接解决报错，因为当程序真正运行到构造函数这一步时，a模块早就加载完毕了。
延迟导入的适用场景非常广：
- 两个类有方法级的互相调用
- 某个函数内部才需要访问对方模块的工具函数
- 模块顶层的常量互相引用但实际上可以通过函数封装来避免
我前几年接手过一个内部工具项目，核心是两个模块互相调用对方的数据类，顶层 import 完全乱掉。最开始面对那段代码，我甚至不敢轻易下手改，因为一动 import 就可能全盘崩。后来我先用了延迟导入，把互相引用的部分全部挪进方法内部，项目立刻恢复可运行状态，后续才逐步做架构清理。
3.2 延迟导入的代价与隐患
延迟导入看起来很方便，但不能无脑用。它有几个明显的代价：
第一，每次调用函数都要重新执行一次 import 语句。虽然 Python 的sys.modules缓存保证了这个操作的开销相对小，但它仍然是多余的查找和字典访问，在高频调用场景下会带来可观测的性能损耗。
第二，它把依赖关系从“一眼能看透”变成了“隐藏很深”。模块顶层看不到这个模块到底依赖了谁，工具依赖扫描、静态分析全部失效。对刚接手代码的人来说，这是一种额外的理解成本。
第三，它掩盖了设计问题。这一点我觉得是最重要的。如果你在每个文件里都塞延迟导入来绕循环依赖，那说明你的模块边界划分大概率有问题。延迟导入是止血手段，不是根治方案。
我个人的经验：当循环导入涉及的模块数量不超过三四个，且交叉引用的地方只有两三处，延迟导入作为短期方案完全可行。但如果交叉引用点很多、模块层级很乱，就不要在延迟导入这条路上走太远，直接考虑重构。
3.3 延迟导入的两种位置选择
同样是延迟导入，放在“方法内部”和放在“模块末尾”效果完全不同。
方法内部的做法上面已经展示了。模块末尾的做法长这样：
# b.py 尾部 from a import A这种写法的用意是：先定义好b.py里所有顶层内容，最后才执行import a。只要a模块的执行不会在底层反过来需要b的某个尚未定义的名字，就有机会跑通。但这种做法对执行顺序的依赖非常强，换一个入口文件就可能整套失效，我并不推荐。
放在方法内部是更稳妥的延迟。因为它把触发时机延后到了“运行时”，而不是“模块加载时”。模块加载阶段的问题，全部被绕开了；运行时阶段对方模块早就完整加载，不存在空壳问题。
4. 常规解法二：重构模块依赖关系
4.1 从架构层面拆解循环依赖
延迟导入是手段，真正的出路是让模块之间不再“互相依赖”。这里要先区分一个概念：A 模块依赖 B，B 模块依赖 A，这叫双向依赖；如果 A 和 B 同时依赖 C，C 谁都不依赖，这叫单向依赖，是健康的架构。
处理循环导入的最高频手段，就是“抽取公共部分到第三个模块”。
拿订单和客户的例子来说：
# models.py —— 独立的数据定义模块 class OrderData: pass class CustomerData: pass# customer.py from models import CustomerData class Customer: def __init__(self): self.data = CustomerData()# order.py from models import OrderData class Order: def __init__(self): self.data = OrderData()两边都只依赖models.py，互不打扰。这就是把“双方共同需要但又容易纠缠的东西”抽出来，放到独立模块里。
抽取公共模块这件事，最忌讳的是想做“完美设计”再动手。实际项目中，我通常用三步走的思路：
第一步，把循环导入的报错点列出来，找到双方在顶层互相引用的那个名字。 第二步，判断这个名字是属于“纯数据/纯类型/纯工具函数”，还是属于“业务逻辑/服务类”。 第三步，如果是前者，压到公共模块里；如果是后者，就要考虑更复杂的拆分方式，比如再抽一层服务层或中间层。
4.2 依赖倒置思路的实战应用
有些时候，两个模块互相引用的是对方的核心业务类，直接抽公共模块会很别扭。比如订单模块需要调用“客户模块的积分计算逻辑”，客户模块需要调用“订单模块的金额统计逻辑”。这时候抽“公共数据类”解决不了根本问题。
更好的思路是依赖倒置：把“被依赖的东西”从具体模块提升到接口层或协议层。
举一个实际见过的结构。某个项目里user.py和notification.py互相引用，user要发通知，notification要查用户信息。重构之后，代码变成了这样：
# notify_service.py —— 定义接口，不依赖具体实现 class NotificationSender: def send(self, user_id, message): raise NotImplementedError# user.py from notify_service import NotificationSender class UserService(NotificationSender): def send(self, user_id, message): # 实现具体的通知发送逻辑 pass def register(self, username): # 注册逻辑 self.send(username, "欢迎注册")# notification.py from user_service_interface import UserDataprovider class NotificationProcessor: def __init__(self, user_provider: UserDataprovider): self.user_provider = user_provider def process(self, user_id): user_data = self.user_provider.get_user(user_id) # 处理通知逻辑这里的要点是：notification不再直接依赖user模块本身，而是依赖一个“能提供用户数据的东西”，这个东西可以是接口、抽象基类或者回调函数。模块间从“具体互相引用”变成了“面向接口的单向流动”。
这种重构方式在小项目里看起来有点过度设计，但在模块数量超过十个、后期还会持续增长的系统里，这是性价比最高的做法。它的额外好处是让单元测试变得非常简单——你甚至不需要加载真实的对端模块，传一个 mock 对象进去就行。
4.3 模块访问入口统一放行的模式
还有一种在中大型项目里很常见的做法：把跨模块访问统一收口到一个“注册中心”模块里，所有互相 import 的需求都变成对注册中心的单向依赖。
# registry.py _registry = {} def register(name, module): _registry[name] = module def get(name): return _registry.get(name)使用方式：
# a.py import registry class A: def __init__(self): b = registry.get('B')# b.py import registry class B: def __init__(self): a = registry.get('A')初始化时，由某个入口文件统一把模块注册进去。这个模式相当于把“运行时依赖查找”做了集中化，让循环依赖的破坏力被限制在注册阶段。适合模块众多、必须快速验证的场景。
5. 解法对比与边界分析
5.1 三种方案的适用场景对照
我用一个表格把前面几节的核心方法做一个横向对比，方便你查漏补缺：
| 方案 | 改动成本 | 对架构的要求 | 适用场景 | 缺点 |
|---|---|---|---|---|
| 延迟导入 | 低 | 无 | 类方法级别互相调用、模块数量少 | 隐藏依赖关系、损耗微小性能 |
| 抽取公共模块 | 中 | 中 | 互相引用的是数据类/工具函数 | 需要额外设计模块边界 |
| 依赖倒置/接口化 | 高 | 高 | 业务逻辑互相嵌套、系统长期演化 | 初期工作量较大，抽象层需要维护 |
从我个人的项目经验来说，一个比较务实的节奏是：先用延迟导入把眼前的问题止血，紧接着的一两个迭代周期内完成公共模块抽取或接口化改造。不要把延迟导入当成终点。
这里插一句，我踩过最狠的一个跟延迟导入相关的坑是：一个服务里同时存在多段延迟导入，某个第三方库在特定情况下触发了奇怪的初始化顺序，结果延迟导入执行时对端模块“已经加载完了但确实还没定义某个名字”，报错变成了AttributeError。那个错误排查了整整一个下午，最后才发现问题根源是第三方库的__getattr__干扰了模块属性查找。所以不要以为延迟导入一定稳。
5.2 最容易被忽略的隐藏陷阱：重复执行模块代码
聊到解决方案之外，还有一个隐藏很深的坑值得单独拎出来讲。
当你修复循环导入后，程序不报错了，但如果你观察发现“某些模块级别的变量被重置了”或“某些初始化操作执行了两遍”，那说明你的修复方式触发了一个新问题：同一个模块被当作两个不同名字加载了。
最常见的原因是大写文件名、不同路径下的同名文件、大小写不敏感文件系统之间的差异。比如之前有人在项目里建了一个models.py，后来又在另一个目录建了Models.py，两个文件内容一样但模块名不同。循环导入确实没了，因为它们是两个独立的模块对象，各 import 各的。但很多模块级状态也被隔离成了两份，莫名其妙出 bug。
排查这种问题的方法：
import sys for name, module in sys.modules.items(): if 'models' in name.lower(): print(name, module.__file__)看看同一个模块是不是在sys.modules里出现了多个条目。如果是，就去查是不是文件路径、命名规范的问题。这个细节虽然跟循环导入的报错没有直接关系，但几乎所有“改完代码后虽然不报错了但行为更怪异了”的现场，最终都能扯到这个原因上。
6. 高级话题：类型检查与循环导入的共处方式
6.1 在类型注解中使用 TYPE_CHECKING
循环导入还有一个非常常见的隐藏场景：代码里根本没有实际的运行时相互引用，只是在类型注解里写了对方模块的类型，结果也被循环导入搞得报错。
很多现代项目大量使用类型注解来提升可读性，比如：
# consumer.py from models import Model def process(item: Model) -> None: pass如果models.py恰好也 import 了consumer.py，循环导入问题就可能被类型注解暴露出来。但实际上，这些类型注解在运行时根本不需要真的加载那个模块。
解决方案是使用typing.TYPE_CHECKING：
# consumer.py from typing import TYPE_CHECKING if TYPE_CHECKING: from models import Model def process(item: "Model") -> None: passTYPE_CHECKING是一个特殊的变量：它在运行时永远是False，也就是说if TYPE_CHECKING里的 import 语句在运行时不会执行。但类型检查工具（比如 mypy、pyright）在处理这个文件的时候，会把它当作True，从而正确解析类型注解。
Python 3.11 之后的部分类型注解用法可以做进一步简化，比如：
from typing import TYPE_CHECKING if TYPE_CHECKING: from models import Model def process(item: Model) -> None: pass但这里有个版本兼容问题：有些旧版本解释器在函数定义时就会解析注解字符串。如果类型对象在运行时不存在，可能报NameError。所以最稳妥的写法是把类型注解写成带引号的字符串形式，等真正需要求值的时候再解析。
6.2 模型继承与循环依赖的终极解法
如果两个模块互相继承对方的数据模型，这个循环依赖会格外麻烦。因为继承关系在类定义时就要确定，延迟导入根本来不及。
我的建议是：模型类的继承关系不要跨业务模块。也就是说，不要出现order.py里的类继承了customer.py里的类，同时又反过来让customer.py里的某个类继承order.py里的类。这种设计在几乎所有编程语言里都是严重反模式。
遇到这种结构，比较合理的做法是：
- 把两者的公共基类单独抽到一个
base/models.py或common/entities.py文件里。 - 两个业务模块分别继承这个公共基类。
- 任何业务模块都不再直接相互继承。
如果是因为“订单也是某种客户资产”之类的业务语义导致的设计困境，优先考虑组合而不是继承。组合的意思是：订单实例持有一个客户实例的引用，而不是订单类去继承客户类。这种转化能把类定义期的依赖转换成运行期的对象关系依赖，循环导入的紧耦合就松掉了。
7. Python 官方机制层面还有哪些坑要提前打预防针
7.1 sys.modules 的操作陷阱
关于sys.modules，有一些骚操作在线上项目里真的出现过，我想单独讲一讲。
某些老代码为了绕过循环导入，会在模块里手动操作sys.modules，比如：
import sys import b sys.modules['a'] = globals()这种操作的含义是：把当前模块的全局命名空间直接放进sys.modules，让别的模块在import a的时候拿到当前执行中的这个模块对象。在早期确实能解开一部分相互引用的问题，但它带来的问题很严重：
一是破坏了模块系统的可预测性。 二是模块加载过程中的状态被强行暴露给了其他模块，对方拿到的是只初始化到一半的模块。 三是 Python 内部依赖sys.modules的一致性，一旦被篡改，后续 import 机制可能出现难以排查的怪异行为。
我的忠告是：永远不要在生产代码里对sys.modules做这种赋值操作。遇到循环导入就老老实实用前面几节的方法解决。手动改sys.modules等于在心脏上做手术，只有等大型框架的源码阅读时才需要理解这个机制。
7.2init.py 中常见的隐藏触发点
还有一种循环导入，表面上看两个文件没有互相 import，问题出在包结构上。
当你有这样的包结构时：
mypackage/ __init__.py a.py b.py如果__init__.py里写了：
from mypackage.a import A from mypackage.b import B而a.py里又写了from mypackage import something，那么__init__.py和a.py之间就会产生循环导入。
这种问题的排查难度比普通两个文件互相 import 高得多，因为报错位置不一定直接指向__init__.py。经验法则如下：
- 不要在
__init__.py里做太重的跨模块导入。 - 如果
__init__.py必须导出多个模块中的名字，优先考虑在包内所有模块加载完成后再统一导出。 - 复杂包结构下，
from mypackage import something这种写法非常容易触发循环，改成from mypackage.a import something会更安全。
我在做某个数据处理项目时就遇到过类似的包结构问题。当时整个包有十几个子模块，__init__.py为了对外提供简洁 API，把所有核心类都导了一遍，结果任何一个子模块内部稍微引用一下包名，就会形成循环环。后来我把__init__.py里的 import 全部改成了模块内部的局部导入，API 层通过另外的public_api.py提供，问题才彻底解决。
7.3 动态导入与import的老旧写法
有一定年头的项目里，还能看到直接用__import__函数动态导入模块的代码。这种写法在循环导入场景下也会产生额外风险，因为__import__的参数是字符串，天然逃过了静态检查，而且执行时机和执行上下文都可能和普通 import 不同。
现在官方推荐的动态导入方式是importlib.import_module：
import importlib def get_b(): return importlib.import_module('b')在延迟导入的基础上，用import_module会让代码更明确，也更容易做统一处理。不过记住一个点：无论你怎么动态导入，循环依赖的本质不变，只是把它推到了更晚的时候爆发。
8. 极简排查清单与调试实操
讲了这么多原理和方案，最后给一个可以直接照着做的排查清单。我自己在实际处理循环导入问题的时候，基本就按这几步走，节约了不少时间。
第一步，确认报错类型。ImportError和AttributeError虽然都可能由循环导入引发，但处理方式不同。ImportError多数发生在模块加载阶段，AttributeError往往是模块已经加载但目标名字尚未定义。
第二步，看sys.modules。在报错之前打断点，或者直接在被 import 的模块入口加打印，看对端模块是处于空壳状态还是完整状态：
import sys print(sys.modules.get('a')) print(hasattr(sys.modules.get('a', None), 'A'))第三步，检查入口执行顺序。循环导入跟入口文件关系极大，同一个包从main.py进和从test_a.py进可能表现完全不同。把入口改成最符合业务实际的一个，再观察报错是否消失。
第四步，定位所有顶层 import。打开两个文件，把所有代码行级别非函数内、非类方法内的 import 全部列出来，逐一排查有没有某一个 import 处在“对方还没定义完”的危险时刻。
第五步，选择修复策略。按我的经验优先顺序：能抽公共模块就先抽公共模块，不能的话用延迟导入，实在绕不开业务互相依赖就上接口化设计。
以下是一个可复用的快速诊断脚本，假设报错文件是a.py和b.py：
# debug_import.py import sys import traceback def debug_import(module_name): try: __import__(module_name) print(f"[OK] {module_name} imported successfully") print(f"[INFO] {module_name} object: {sys.modules.get(module_name)}") except ImportError: print(f"[FAIL] {module_name} import failed") traceback.print_exc() # 打印所有 partially initialized 的模块 for name, mod in sys.modules.items(): if mod is None or not hasattr(mod, '__spec__'): continue if getattr(mod.__spec__, 'initializing', False): print(f"[WARNING] Module still initializing: {name}") if __name__ == "__main__": debug_import('a')这个脚本会在失败时打印所有仍在初始化中的模块，通常就是循环导入的参与者。实际项目里可以根据自身模块名去套用。
9. 关于循环导入的几条硬性心得
处理过几十个循环导入问题之后，有些话想直接告诉你，当作最后的经验沉淀。
第一，循环导入不是 Python 的缺陷，它是模块边界设计出问题的报警器。你可以用各种技巧绕过它、隐藏它、延迟它，但最终都得回到“谁该依赖谁”这个问题上。
第二，修复循环导入时，优先级最高的是“让程序重新稳定运行”，其次是“让依赖关系变得清晰可见”。千万不要为了保持“原有结构不动”而堆延迟导入，等模块数量膨胀到一定程度再重构，成本会成倍上升。
第三，配置类代码最容易引发循环导入。如果你的某个文件负责读取配置文件，另一个文件需要根据配置决定导入行为，切记不要在模块顶层互相 import，把配置读取和依赖加载隔离开来。
第四，单元测试阶段就引入循环依赖检测。如果你的项目用pytest，可以考虑在 conftest 里做一层检查，凡是 import 之后模块处于 partially initialized 状态就输出警告。这比等上线后再被线上日志打脸要舒服得多。
第五，被循环导入坑过一次的项目，大概率还会坑第二次。所以第一次修复时，一定要在关键位置留下足够的注释，说明这是为了解决循环依赖而做的延迟导入，还是为了解决循环依赖而抽出的公共模块。长期维护时，注释能救队友一命。
