元宿six单例模式可能是 Python 里被讲滥了、也被用滥了的一个设计模式。我见过不少项目里，为了“全局唯一配置”强行写了一个 __new__ 单例，结果爬虫经常初始化两遍配置，改了一次参数怎么都不生效；也见过另一个团队把所有连接池都套上元类单例，最后写单元测试时状态互相污染，一跑请求就串数据。这些问题的根源，不是“单例模式没用”，而是很多人只记住了单例的写法，没想清楚它解决什么问题、适合什么场景。
这篇文章我把 Python 单例模式相关的知识点完整梳理一遍：从模块级单例到装饰器、__new__、元类，再到线程安全和懒加载的隐藏坑；然后结合实际项目（爬虫、数据分析、量化交易、comfyui 工作流节点这类常见场景）聊聊到底该怎么选、怎么用、怎么避免踩坑。无论你是刚接触设计模式的新手，还是已经写了几年 Python 想彻底搞懂单例细节的老手，应该都能在这篇文章里找到自己需要的答案。
1. 先说结论：Python 里什么时候才值得用单例
很多教程一上来就教怎么写单例，但很少讲“这个项目到底需不需要单例”。我个人的判断标准很朴素：只有当你确实需要“进程内只存在一个实例”这件事本身，才值得引入单例。
1.1 单例真正解决的两类问题
第一类问题是全局状态共享。比如一个配置管理器、一个日志访问入口、一个数据库连接池，多个模块访问同一个对象，保证大家读到的状态一致。如果没有单例，你可能会很痛苦地把 ConfigManager() 实例传来传去，传到最后模块之间互相 import，搞成一团乱麻。
第二类问题是资源复用。有些对象创建成本很高，比如数据库连接池、Redis 客户端、一个包含了数千条规则的事件总线。每次 new 一个不仅浪费内存，还可能导致数据库连接被耗尽。这种场景下，全局保持一个实例是合理的。
1.2 不需要单例的“反例”
但问题就出在这里：很多人把“我想全局访问一个对象”和“这个对象必须单例”混为一谈。比如你只是想在各个模块里拿到同一个配置字典，那完全可以直接定义一个模块级变量，没必要把类本身锁死。
再举一个很常见的反例：数据模型对象。我见过有人给一个 User 类也加上了单例元类，理由是“整个系统只有一个当前登录用户”。这其实是个坏味道——用户对象是有生命周期的，登录、登出、切换账号，每个阶段都可能需要不同实例。如果被单例锁死，登出之后状态怎么清理？这给后面的维护埋了很大的雷。
单例模式适合的是“从程序启动到退出，这个对象始终不变且全局唯一”的场景；如果你的对象可能有多份、有生命周期、有状态变化，单例只会让问题更复杂。如果只是为了避免到处传参，更合适的做法是依赖注入，或者在函数内部通过参数传递。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 模块级单例：Python 里最被低估的写法
我第一次接触 Python 单例是在别的语言项目里，当时第一反应是去找“类似 Java 私有构造函数”的实现。后来在 Python 项目里呆久了才发现，Python 有一个天然的、零成本的单例方案：模块本身就是单例。
2.1 为什么说模块天生是单例
Python 的 import 机制保证同一个模块在同一个进程里只会被加载一次。第二次 import 时，解释器会从 sys.modules 里直接取缓存，不会重新执行模块代码。这意味着一件事：如果你在模块里直接创建一个对象实例，那么整个进程里其实就只有这一份。
所以最简单的单例是这样写的：
python复制# config_manager.py
class ConfigManager:
def __init__(self):
self._data = {}
def load(self, path):
# 从文件或环境变量读取配置
pass
def get(self, key):
return self._data.get(key)
def set(self, key, value):
self._data[key] = value
# 模块底部直接实例化
config_manager = ConfigManager()
其他模块要用的时候，直接 from config_manager import config_manager 就行。不需要任何额外的锁、装饰器、元类，它天然就是全进程唯一。
这种方式在数据分析、爬虫项目里特别实用。我写爬虫的时候，各个爬虫模块、中间件、调度器都要读取数据库连接信息，统一 from config_manager import config_manager，配置加载一次，全局共享。
2.2 模块级单例的懒加载问题
模块级单例有一个绕不开的取舍：如果你在模块顶层直接实例化，那么 import 这个模块的时候，实例就被创建了。 如果实例初始化开销很大，或者需要依赖运行时环境变量，可能会过早加载。
想要懒加载，可以包一层函数：
python复制# config_manager.py
_instance = None
class ConfigManager:
...
def get_config() -> ConfigManager:
global _instance
if _instance is None:
_instance = ConfigManager()
_instance.load("config.yaml") # 真正需要时才加载
return _instance
不过这种方式有个小缺点：调用方必须通过 get_config() 函数访问，而不能再 from config_manager import config_manager。如果团队成员忘了这一点，直接 import 这个模块然后又拿不到实例，会有点绕。
另外，Python 3.7 之后可以在模块里用 __getattr__ 实现“模块级别的懒加载属性”：
python复制# config_manager.py
_config_instance = None
def _create_config():
global _config_instance
if _config_instance is None:
_config_instance = ConfigManager()
return _config_instance
def __getattr__(name):
if name == "config_manager":
return _create_config()
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
这样外部可以继续写 from config_manager import config_manager，而实际实例化被推迟到第一次访问属性时。这套方案兼顾了使用体验和懒加载，缺点是理解成本高一些，不太适合做团队公共约定。
2.3 为什么我最后通常回归模块级写法
从可维护性角度讲，模块级单例有两个不可替代的优势。
第一是没有魔法。新接手的人看代码时，不需要去理解 __new__ 或元类做了什么，他只需要知道“config_manager 这个模块级对象是全局唯一的”就够了。代码是写给人看的，减少魔法就是减少沟通成本。
第二是测试友好。模块级对象可以被很方便地替换：
python复制import config_manager
config_manager.config_manager = FakeConfigManager() # 测试时替换
而如果你用装饰器或元类把类写死成单例，测试时想换掉实例就得额外写重置逻辑，麻烦得多。
所以我的建议是：默认优先使用模块级单例，除非你有明确的理由需要控制实例化逻辑本身。
3. 装饰器版单例：把逻辑从类里剥离出来
如果你不想写模块级对象，又想用一个装饰器让任意类自动变成单例，这个方案很适合。它最大的优点是让类的代码保持纯粹——类本身不需要知道自己是单例。
3.1 用闭包和锁实现基本单例
一个单线程环境下的装饰器版单例非常简洁：
python复制def singleton(cls):
_instance = None
def wrapper(*args, **kwargs):
nonlocal _instance
if _instance is None:
_instance = cls(*args, **kwargs)
return _instance
return wrapper
@singleton
class Database:
def __init__(self):
self.url = "mysql://localhost:3306"
注意这里有个 nonlocal _instance，闭包里修改的是外层函数的局部变量。第一次调用 Database() 的时候创建实例，之后无论怎么调用都返回同一个对象。
但这段代码在并发场景下有一个隐患：两个线程同时第一次调用 Database() 时，可能都判断 _instance is None，然后各自创建一个实例。虽然概率不高，但一旦发生，全局就出现两个对象了。所以我们加一把锁：
python复制import threading
def singleton(cls):
_instance = None
_lock = threading.Lock()
def wrapper(*args, **kwargs):
nonlocal _instance
if _instance is None:
with _lock:
if _instance is None:
_instance = cls(*args, **kwargs)
return _instance
return wrapper
这就是经典的双检锁（Double-Checked Locking）模式：先做一次快速判断避免每次调用都加锁，只有发现实例为空时才进入临界区，进入临界区后再次判断。在 CPython 的 GIL 下，这种写法是可靠且高效的。关于线程安全，后面专门有一节展开说。
3.2 装饰器单例遇到构造函数参数怎么办
一个很容易被忽略的问题是：如果被装饰的类构造函数需要参数，那么不同参数调用会发生什么？
python复制@singleton
class Database:
def __init__(self, host: str):
self.host = host
a = Database("host1")
b = Database("host2")
print(a is b) # True
print(b.host) # 仍然是 "host1"
第二次调用 Database("host2") 会直接返回第一次创建的实例，参数会被静默忽略。这在某些场景下符合预期，但在另一些场景下就是灾难。比如你想按不同环境创建两个不同的数据库连接，结果第二个参数直接被丢弃。
所以在使用装饰器版单例时，一定要在文档或注释里明确告诉调用方：不要指望后续调用的参数会生效，实例只认第一次构造时的参数。 如果你想支持“按参数区分实例”，那应该用注册表模式而不是单例模式，这个后面会讲到。
3.3 装饰器单例的测试痛点
装饰器版单例的测试问题在于替换实例不方便。假如你需要测试某个模块在数据库连接失败时的行为，必须先把全局实例换成 mock 对象。但装饰器内部持有 _instance，你没有办法从外部访问它。
我常用的做法是在装饰器里额外暴露一个 reset 函数：
python复制def singleton(cls):
_instance = None
_lock = threading.Lock()
def wrapper(*args, **kwargs):
nonlocal _instance
if _instance is None:
with _lock:
if _instance is None:
_instance = cls(*args, **kwargs)
return _instance
def reset():
nonlocal _instance
with _lock:
_instance = None
wrapper.reset = reset
return wrapper
测试时：
python复制def test_database_connection_error(monkeypatch):
Database.reset() # 清掉全局实例
monkeypatch.setattr(Database, "__init__", lambda self: (_ for _ in ()).throw(ConnectionError()))
with pytest.raises(ConnectionError):
Database()
Database.reset()
这个技巧帮我省了不少事。如果你打算在项目里推广装饰器版单例，建议一上来就把 reset 加进去，否则后面写测试时会很痛苦。
4. 用 __new__ 实现单例：最直观也最容易踩坑的写法
__new__ 方法在 Python 中负责创建实例，__init__ 负责初始化实例。很多人觉得只要在 __new__ 里控制一下返回同一个实例就够了，但第二天就会撞上一个看似诡异的现象：对象确实是同一个，但属性每次都会被重置。
4.1 基础写法与 __init__ 重复执行的问题
看这段代码：
python复制class Singleton:
_instance = None
def __new__(cls, *args, **kwargs):
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self, value: int):
self.value = value
a = Singleton(10)
b = Singleton(20)
print(a is b) # True
print(a.value) # 20，而不是 10
对象是同一个，但因为每次调用 Singleton(...) 都会触发 __init__，所以 value 被第二次调用覆盖了。很多新手在这时候一脸懵：明明单例生效了，为什么状态不断被重置？
问题的本质是：单例模式控制的是“对象的数量”，但 Python 的实例化过程由 __new__ 和 __init__ 共同完成。 如果你只重写 __new__，__init__ 依然会每次都被 Python 自动调用。
4.2 用 _initialized 标记避免重复初始化
解决办法是在类上加一个标志位，确保初始化逻辑只执行一次：
python复制class Singleton:
_instance = None
_initialized = False
def __new__(cls, *args, **kwargs):
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self, value: int):
if not Singleton._initialized:
self.value = value
Singleton._initialized = True
当然，这里有个风格上的问题：_initialized 判断的是“这个类是否已初始化一次”，而不是看具体某个实例。如果你后面再搞子类继承，这个标记就会在父子类之间共享，容易出问题。更严格的写法是把标志放在实例上：
python复制class Singleton:
_instance = None
def __new__(cls, *args, **kwargs):
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self, value: int):
if not hasattr(self, "_initialized"):
self.value = value
self._initialized = True
hasattr(self, "_initialized") 判断的是“这个实例是否已经初始化过”。因为 _instance 是同一个对象，第一次调用后就有这个属性了，后续 __init__ 会被直接跳过。
4.3 __new__ 单例值得注意的边界场景
__new__ 版单例有一个容易让人意外的地方：如果你直接调用 Singleton.__new__(Singleton)，你会绕过正常的初始化流程，拿到一个“半成品”实例——没有 value 属性，也没有 _initialized 标志。这在正常业务代码里几乎不会发生，但如果你写的是类库，被别人以高级用法调用时，就可能成为一个隐藏的坑。
另外，__new__ 版单例其实只是“约定”层面的单例。Python 的 cls._instance 是类变量，任何人都可以直接修改 Singleton._instance = None 来强制重置。这既是缺陷也是优点：测试时反而容易重置，但也要提醒团队不要随意动类变量。
5. 元类版本：把单例规则固化成类的“类”
元类是很多人一听就头疼的概念，但其实理解它不需要特别高深的数学。可以这样想：普通类负责创建实例，元类负责创建“类”本身。 当你定义 class A(metaclass=Meta) 时，Meta 控制的是 A 这个类怎么生成、怎么被调用。
单例元类的原理是重写元类的 __call__ 方法。我们知道，调用一个类 A() 实际是执行 type.__call__(A)，这个 __call__ 内部会调用 A.__new__ 和 A.__init__。如果我们拦截这个“类的调用”环节，就能在实例创建之前就告诉它“已经有一个实例了，直接返回吧”。
5.1 基础的元类单例实现
python复制class SingletonMeta(type):
_instances = {}
def __call__(cls, *args, **kwargs):
if cls not in cls._instances:
cls._instances[cls] = super().__call__(*args, **kwargs)
return cls._instances[cls]
class Config(metaclass=SingletonMeta):
def __init__(self):
self.debug = False
a = Config()
b = Config()
print(a is b) # True
这里的 cls._instances 其实是 SingletonMeta._instances，但它通过 cls 可以访问到。字典的 key 是具体的类对象，value 是实例。
元类方案对比前面几种方案最大的优势是：类的使用方完全无感。 调用方不需要知道这是单例类，不需要通过 get_instance() 方法，就正常 Config() 就能拿到唯一实例。
5.2 元类单例的懒加载与线程安全
上面的元类实现默认也是懒加载的——只有在第一次真正调用 Config() 时才创建实例，而不是 import 时创建。
线程安全方面，在 CPython 的 GIL 下，上面这段代码大概率不会出问题，但严格来讲它并不是“原子”的。如果你想在生产环境求个心安，加一把锁：
python复制import threading
class SingletonMeta(type):
_instances = {}
_lock = threading.Lock()
def __call__(cls, *args, **kwargs):
if cls not in cls._instances:
with cls._lock:
if cls not in cls._instances:
cls._instances[cls] = super().__call__(*args, **kwargs)
return cls._instances[cls]
注意这里 lock 是加在 cls._lock 上，不同类会共享同一个 _lock。如果你的项目里有大量不同的单例类，它们之间会有轻微锁竞争，但对绝大部分应用来说可以忽略。
5.3 元类方案下一个容易搞错的问题：继承
元类单例有一个非常经典的坑：如果子类继承了一个元类单例父类，子类会各自得到一个新的实例，还是共享父类的实例？
看这段代码：
python复制class Base(metaclass=SingletonMeta):
pass
class Child(Base):
pass
a = Base()
b = Child()
print(a is b) # False
答案是 False，子类和父类各自有各自的实例。原因很简单：SingletonMeta.__call__ 的 cls 参数会是调用时的实际类。Base() 时 cls 是 Base，Child() 时 cls 是 Child，它们在 _instances 字典里是不同的 key，所以各自创建自己的实例。
这在很多场景下其实是合理的设计：每个子类都有自己独立的单例状态。但如果你想让整个继承体系共享同一个实例，那就得在 __call__ 里强制使用某个固定类作为 key，比如总是用 Base。不过这种需求比较少见，而且会破坏直觉，所以通常不建议。
还有一个更隐蔽的问题：如果父类已经创建了实例，子类继承时 _instances 里没有子类的 key，子类会创建一个全新的实例。这时候子类的 __init__ 会被执行，但父类的 __init__ 不会被子类自动调用（Python 的继承机制），所以子类可能处于一个“看似继承了父类属性、实际上完全没初始化”的状态。写完元类单例，最好补一个子类化的单元测试确认行为符合预期。
6. 线程安全与懒加载：单例的并发生死线
单例的代码看起来简单，真到多线程项目里才见真章。下面把并发相关的问题一次性说透。
6.1 GIL 并不能替你保证“只初始化一次”
有些 Python 开发者认为，因为 CPython 有 GIL（全局解释器锁），所以“多线程不会真正并行执行 Python 字节码”，单例不需要加锁。这个说法是错误且危险的。
GIL 确实保证同一时刻只有一个线程执行 Python 字节码，但它不保证多条字节码指令之间不被切换。比如 _instance 的判空和赋值是两个操作，中间完全可能被另一个线程插进来。以最基础的实现为例：
python复制def get_instance():
global _instance
if _instance is None: # 字节码 1： LOAD/COMPARE_OP
_instance = cls() # 字节码 2： CALL_FUNCTION/STORE_GLOBAL
return _instance
线程 A 执行完 if _instance is None 后，GIL 可能被切走；线程 B 也执行了同样的判断，也看到 _instance is None；然后 A 创建实例，B 又创建了另一个实例。最后全局就有两个实例，单例失效。
所以，只要涉及多线程并发访问，就必须用锁或其他同步机制来保证“检查—创建”的原子性。
6.2 双检锁在 Python 下的实际用法
双检锁是单体模式里最经典的高性能并发写法：
python复制import threading
class Singleton:
_instance = None
_lock = threading.Lock()
def __new__(cls, *args, **kwargs):
if cls._instance is None: # 第一次快速检查
with cls._lock:
if cls._instance is None: # 加锁后再次检查
cls._instance = super().__new__(cls)
return cls._instance
好处是：一旦实例创建完成，之后每次调用只需要做一次空的 if 判断，不再需要加锁，性能开销极小；而在首次创建阶段，锁保证了只有一个线程能真正执行实例化。
需要注意的是，双检锁在不同编程语言中有内存可见性问题，在 Python 里因为 GIL 的存在，实际很少出问题。但如果你用 Jython、IronPython 等没有 GIL 的解释器，或者在 PyPy 里做更极端的优化，就需要更谨慎。大多数人只跑 CPython，所以这套写法基本够用。
6.3 反面案例：把 requests.Session 直接做成全局单例
我见过不少爬虫项目里有人这么做：
python复制session = requests.Session() # 模块级单例，全局共享
听上去很合理：Session 对象维护连接池和 Cookie，全局一份不是完美符合单例理念吗？
问题在于：requests.Session 并不是线程安全的。官方文档明确说明不同线程应该使用各自的 Session 实例。多个线程共用同一个 Session 时，Cookie 的读写可能互相干扰，请求参数也可能在并发时错乱。如果你把 Session 做成单例全局共享，那就等于用单例制造了一个并发隐患的定时炸弹。
正确的做法是使用 threading.local() 为每个线程维护独立的 Session：
python复制import threading
import requests
_local = threading.local()
def get_session() -> requests.Session:
if not hasattr(_local, "session"):
_local.session = requests.Session()
return _local.session
这个例子告诉我们一个很关键的认知：单例只保证“只有一个对象”，不保证“这个对象线程安全”。 共享和线程安全是两个维度的问题。这也是为什么单例模式经常和“多线程冲突”捆绑出现——对象共享得越多，并发问题越容易暴露。
如果你要共享的对象本身不是线程安全的，请谨慎使用单例，优先考虑 thread-local 或连接池等更专业的方案。
7. 实战落地：配置管理、日志、连接池里的应用与坑
前面讲了各种实现方式和并发底层原理，这一节聊点更贴近实际工程的东西：单例到底在哪些项目里真正发挥价值，以及我在这些场景里踩过的坑。
7.1 三个值得用单例的实战场景
场景一：配置管理中心
不管是爬虫、数据分析脚本、还是量化交易回测系统，配置都是天然的全局状态。我做一个量化交易策略回测时，多个策略模块都要读取交易手续费、滑点、数据源路径等参数。用单例配置管理器后，配置只加载一次，所有策略模块都能读到同一份参数，后面调整参数也只需改一处。
python复制class TradingConfig(metaclass=SingletonMeta):
def __init__(self):
self.fee_rate = 0.001
self.slippage = 0.0005
self.data_path = "./data"
场景二：日志访问入口
Python 的 logging 模块内部其实已经实现了类似单例的注册表机制。logging.getLogger(name) 在内部维护了一个 Logger.manager.loggerDict 字典，相同名字的 logger 永远返回同一个对象。
这就是我前面提到的“注册表模式”，可以理解为单例模式的扩展版：它不仅仅支持一个“全局唯一对象”，还支持“同一个名字对应同一个对象”。在量化交易或数据分析项目里，不同模块可以 get_logger("trade")、get_logger("data")，同名 logger 全局共享，不同名字可以分开配置级别，既灵活又不失全局唯一性。
如果你的需求是“某一种类只能有一个实例”，优先考虑注册表模式而不是硬编码的全局单例。
场景三：数据库连接池 / Redis 客户端
数据库连接池对象本身是重量级的，而且需要全局共享连接状态。把它做成单例，能保证各个业务模块访问同一个连接池：
python复制class MySQLPool(metaclass=SingletonMeta):
def __init__(self):
import mysql.connector.pooling
self.pool = mysql.connector.pooling.MySQLConnectionPool(
pool_name="mypool",
pool_size=5,
host="localhost",
database="test",
)
这里有个细节：如果你的 __init__ 里创建了连接池，第一次调用时它会执行，第二次调用时因为 _instances 已经有实例了，__call__ 会直接返回已有实例，不再执行 __init__。这是元类单例相比 __new__ 方案更干净的地方——不需要手动加 _initialized 标记。
7.2 单例与序列化：pickle 会悄悄造出第二个实例
很多人没意识到，单例类在 pickle 之后可能就不再“单例”了。默认情况下，pickle.loads() 会通过 __reduce_ex__ 创建对象，这个过程中会调用类似 object.__new__(cls) 的逻辑，绕过你的单例控制，直接生成一个全新实例。
解决方法是给类实现自定义的 __reduce__：
python复制class Config(metaclass=SingletonMeta):
def __reduce__(self):
return (Config, ()) # 反序列化时调用 Config()，会走单例逻辑，返回唯一实例
但这里有个隐藏的问题：如果用 pickle 把一个单例对象序列化到磁盘，再在另一个进程里反序列化，那么每次反序列化都会调用 Config()。如果你使用了元类单例，它在另一个进程里也会创建新的“唯一实例”——单例只在单个进程内有效，跨进程无法保证。
如果你需要多进程共同访问同一个配置或状态，正确方案是用分布式缓存（Redis）、共享内存或文件锁，而不是期望单例模式跨进程生效。
7.3 单元测试时如何重置单例状态
单例最让测试工程师头疼的地方是状态污染。假设你在测试用例 A 里设置了 config.set("key", "value1")，用例 B 一开始读到的可能还是 A 留下的状态。为了让每个测试用例从干净状态开始，你需要一个重置机制。
用模块级单例的话，直接替换模块变量就行；用 __new__ 版本，可以直接重置类变量；但用元类版本时，_instances 被封装在元类内部，不容易直接修改。
我一般会给元类增加一个 reset 类方法：
python复制class SingletonMeta(type):
_instances = {}
def __call__(cls, *args, **kwargs):
...
@classmethod
def reset(mcs, cls=None):
if cls is None:
mcs._instances.clear()
else:
mcs._instances.pop(cls, None)
然后在测试 fixture 里：
python复制@pytest.fixture(autouse=True)
def reset_singletons():
yield
SingletonMeta.reset()
这样每个测试结束后都能清空所有单例，避免用例之间互相污染。
7.4 打包成 exe 和多进程场景下的“进程间单例”
还有一个在社区里经常被问到的需求：程序打包成 exe 后，用户双击两次，结果打开了两个进程。这时候我们希望“整个操作系统里只允许一个实例运行”。
这是“进程间单例”，和本文前面讨论的类单例不是一回事。常规做法是绑定一个本地端口或创建文件锁。我用过最省事的方式是绑定 localhost 的一个固定端口：
python复制import socket
def is_already_running(port: int) -> bool:
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
s.bind(("127.0.0.1", port))
return False # 绑定成功，说明没有其他实例
except OSError:
return True # 端口被占用，说明已有实例在运行
finally:
s.close()
注意 Windows 和 Linux 在文件锁 API 上不一样，端口绑定方案跨平台更通用，但如果系统防火墙规则激进，偶尔会有误判。这个问题在 Python 社区被反复提到，适合作为“单例模式只是进程内概念”的延伸补充。
7.5 一个 comfyui 工作流里的配置污染案例
前阵子帮朋友排查 comfyui 工作流节点的问题，一个自定义节点需要从共享配置里读取模型路径，结果多个节点实例之间配置串了。原因是节点类被设计成了单例，配置对象也是全局单例，于是不同节点之间根本无法隔离自己的状态。
这暴露了单例模式的一个适用边界：单例适合“全局共享一份状态”的场景，不适合“多个上下文各自需要自己状态”的场景。 在 comfyui 这种插件系统里，不同工作流节点可能需要不同的参数配置，如果硬要用单例，轻则状态串扰，重则整个工作流行为不可预期。
我当时给出的建议是：把节点从单例改成普通类，状态按实例管理；对于需要全局共享的配置，用按工作流 ID 隔离的字典，而不是一个赤裸裸的全局单例：
python复制_workflow_configs = {}
def get_workflow_config(workflow_id: str):
if workflow_id not in _workflow_configs:
_workflow_configs[workflow_id] = {}
return _workflow_configs[workflow_id]
这种“按 key 隔离的注册表”比单一全局单例更安全，也更贴合插件系统的实际场景。
8. 不同场景下的选型速查表
前面讲了五种常见的单例实现方式，最后我总结了一张表，方便你根据实际情况直接“抄作业”。
| 实现方式 | 代码复杂度 | 线程安全 | 懒加载 | 测试重置难度 | 适用场景 |
|---|---|---|---|---|---|
| 模块级对象 | 最低 | 天然安全（只要初始化不依赖运行时状态） | 需要额外写 __getattr__ |
低 | 大多数项目首选 |
| 装饰器版 | 中低 | 需自己加锁 | 天然懒加载 | 中（可通过 reset 函数解决） | 多类都需要单例，不想改类内部逻辑 |
__new__ 版 |
中 | 需自己加锁 | 天然懒加载 | 低（可重置类变量） | 简单项目，类本身自己想控制实例化 |
| 元类版 | 中高 | 需自己加锁 | 天然懒加载 | 中高（需提供 reset 方法） | 类库、框架，使用方无感 |
| 注册表模式 | 中 | 需自己加锁 | 天然懒加载 | 中 | 需要按 key 区分多个唯一实例 |
我的个人经验是：有 70% 的场景用模块级单例就够了，20% 的场景用注册表模式比硬单例更好，只有不到 10% 的类库设计场景才需要元类。 很多人一上来就上元类的复杂写法，看起来很酷，但没有解决实际问题，反而增加了团队理解成本。
关于线程安全，还有一个容易被忽略的点：如果单例对象只是被读取而不修改，其实不需要加锁；但一旦某个线程在初始化后可能写状态，就要考虑同步。 模块级单例在 Python 启动早期 import 阶段创建实例，由于 import 是单线程执行的，很多情况下可以天然避开并发初始化问题。这也是我偏好模块级单例的另一个原因。
最后再分享一个在实际项目里救过我的小技巧：如果是团队协作，最好在单例类里加一个 reset 或者 destroy 方法，哪怕只是把内部状态清空。因为测试、热重载、动态配置更新都需要“重新初始化”的能力。很多人把单例设计成一个彻底无法重置的黑盒，最后反而被自己坑了。
单例模式本身没有对错，关键是它和你的业务模型是否匹配。写代码之前先问自己一句：这个东西真的需要“进程内唯一”吗？如果答案是肯定的，再挑一种实现方式；如果答案只是“我不想每次传参”，那设计上可能还有更好的路可以走。