循环导入报错源于模块“半初始化”状态：sys.modules已注册但代码未执行完，导致from A import B时B尚未定义。常见于Django/FastAPI等框架的双向引用，需通过拆分共享逻辑、延迟导入、绝对导入及显式__init__.py接口控制来解决。
循环导入报错（ImportError: cannot import name 'X' from partially initialized module 'Y'）不是语法错误，也不是环境没装包——它发生在模块已注册进 sys.modules、但代码还没执行完的“半初始化”状态。开发时可能一切正常，一上生产就崩，因为触发时机依赖导入顺序和运行路径。
为什么 from A import B 会突然找不到 B
Python 导入时先在 sys.modules 中占个位，再执行模块体。如果此时另一个模块反向试图从它里面拿东西，而那个东西（比如函数、类）还没定义到那一行，就会报错。
- 常见现象：本地跑通，CI 或线上部署时报
partially initialized module - 典型场景：Django 的
models.py和signals.py互相导入；FastAPI 的main.py和router.py在初始化时引用对方的实例 - 关键点：错误不是出在 import 语句本身，而是出在被导入模块中「尚未执行到」的那个对象定义位置
重构逻辑：把紧耦合拆成松依赖
循环导入本质是设计问题，不是导入技巧能绕过去的。优先考虑是否真需要双向引用。
- 把共享逻辑抽成独立模块，比如
utils.py或core/types.py，让 A 和 B 都只单向依赖它 - 检查是否误把「运行时需要的对象」写在了模块顶层。例如：在
models.py里直接调用from tasks import send_email，而tasks.py又导入了这个 model —— 改成只在函数体内导入 - 用协议（
Protocol）或抽象基类（ABC）声明接口，避免具体类跨模块强引用
延迟导入：在函数/方法内部 import
把 import 移到真正用到的地方，能避开模块加载期的依赖链。这是最常用、见效最快的补救手段。
Secure Python Code Sandbox
下载
安全 Python 代码沙箱：在隔离的沙箱中执行任意 Python 代码，预装 requests、NumPy、pandas 库。返回 stdout、stderr。
- 适用条件：该模块只在特定函数路径下才用，且不涉及类定义、装饰器参数、默认参数值等需要模块级解析的场景
- 示例：原写法
from services.auth import verify_token在文件顶部 → 改为在验证函数里写from services.auth import verify_token - 注意：不能用于
@decorator(verify_token)这类装饰器参数，因为装饰器在定义时就要求对象存在；也不能用于def f(x: VerifyToken = verify_token)这种带默认值的类型注解 - 性能影响极小：Python 缓存已导入模块，重复 import 不会重载，只是查
sys.modules
绝对导入 + __init__.py 显式暴露
相对导入（from . import X）容易放大路径歧义，加剧循环风险。强制使用绝对路径，并控制包的公开接口。
- 确保每个包目录都有
__init__.py（哪怕空文件），否则 Python 不认为它是包 - 在
__init__.py中显式导出稳定接口：from .models import User, Order，然后外部统一用from myapp.models import User，避免跨子模块乱穿 - 禁用
from .submodule import *，它会让导入关系不可控，IDE 和静态检查也难追踪
真正棘手的循环导入，往往藏在看似无害的信号注册、插件自动发现、或 ORM 关系定义里。别只盯着报错行，得顺着 sys.modules 里那个 “partially initialized” 模块，看它卡在哪一行没执行完——那才是真实断点。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
