打开任何一个 Python 项目的配置模块，你大概率都会碰到“单例模式”这个词。它不算一个多高深的设计模式，却是一个绕不开的话题：日志句柄、数据库连接池、全局配置、路由表、线程池管理器……这些场景的共通点只有一个——全局只需要一个实例，多出来的都是浪费，甚至是隐患。Python 里实现单例的方式五花八门，从最简单的模块级变量到__new__、装饰器、元类，一条路走到黑的人不少，踩坑的人更多。
我写 Python 也有十年上下了，见过“单例模式”被滥用成卡顿 BUG 的样子，也见过因为少加一把锁导致线上配置错乱的现场。这篇文章就把我这些年用过的实现方式、踩过的坑、排查思路一次性讲清楚。不管你是刚入门的初学者，还是已经在团队里做架构设计的老手，都应该能在这里找到比“背一个模板”更有用的东西。
1. 为什么我们需要单例模式
1.1 单例到底解决了什么问题
单例模式的核心诉求其实是一句话：保证某个类在整个程序生命周期里只有一个实例，并且提供一个全局访问点。为什么会有这种需求？因为现实世界里的很多“资源”本质上就是全球唯一的。
举一个最常见的例子：日志对象。假设你的项目里有十个模块，每个模块都随手Logger()创建一个日志实例，那么你写日志时会发现文件句柄重复打开、日志交错、甚至因为多个句柄没有 flush 导致最后几行日志丢失。如果你用单例模式，所有模块拿到的都是同一个日志对象，写入顺序天然就是一致的，所有日志都在一个文件描述符上排队输出。
数据库连接池同理。你不可能每个业务请求都新建一个连接池，那意味着连接数会不受控制地膨胀，数据库压力的罪魁祸首往往就是这么来的。配置管理器更不用说了，项目启动之初读取一次配置，全进程共享同一个配置对象，任何地方改了一处，其余地方都能感知到。单例模式解决的就是这种“全局唯一资源”的共享与管理问题，它提供一个统一的访问入口，同时避免重复创建带来的开销和混乱。
1.2 什么时候不该用单例
我见过不少同学把单例当成万能药，什么类都往单例里塞，这是一个必须纠正的倾向。单例模式本质上是在“全局唯一”和“灵活性”之间做取舍，如果这个类本身的职责就不需要全局唯一，硬套单例只会让测试变得痛苦、代码耦合变得更严重。
举个例子，你在写一个数据处理管道，里面有个DataProcessor类，它有很多状态，比如当前批次、转换规则。如果你把它做成单例，那么并行测试的时候，两个测试用例会互相污染状态，你还没法轻易重置。这种时候，你应该让DataProcessor是普通类，由上层显式创建和管理，或者用依赖注入把实例传进去，而不是自己偷偷藏一个全局访问点。
判断一个类该不该做成单例，我的经验是看三个条件：一，逻辑上是否天然具备“全局唯一”的属性，比如配置、日志、连接池；二，实例是否有共享状态，且这个状态需要被多个模块看到；三，——最重要的——这个类能否被轻易替换？如果你只是为了让代码“显得统一”而用单例，那趁早放弃，用工厂或者依赖注入更靠谱。单例不等于全局变量，它是“有节制的全局”，滥用它只会让代码变成一锅乱炖。
1.3 Python的特殊之处：模块和内置机制
聊 Python 的单例模式，有一个绕不开的语言特性：import机制本身就是天然的“单例”。当你第一次import module时，Python 解释器会把这个模块的代码执行一遍，然后把模块对象放进sys.modules里。之后任何一个地方再import同一个模块，拿到的都是sys.modules里缓存的那个对象，不会再重新执行一遍顶层代码。
这意味着一个非常实用的技巧：你不需要去实现什么Singleton类，直接在模块里定义一个实例，然后让所有调用方都从模块里拿这个实例，天然就是单例。这也是很多资深 Python 开发者的推荐做法，因为它的实现成本最低、行为最清晰，而且它是语言层面保证的，比你手写几百行锁逻辑还要可靠。
不过“模块天然单例”也有局限。比如你想把这个实例替换成子类实例，想在运行时重新加载配置，模块级变量就没那么方便了。另外，如果你在模块里定义了Settings()实例，但调用方通过Settings()类自己 new 一个，那就不是单例了。所以我们后面要讨论的几种类级单例实现，依然有它们的价值。
2. 五种常见实现方式与取舍
2.1 模块级变量：最朴素的“写法即单例”
这种实现方式最简单，甚至不需要专门的代码。你新建一个config.py，里面写：
class Config: def __init__(self): self.retry_times = 3 self.timeout = 10 config = Config()然后别人使用时：
from config import config print(config.timeout)这就是一个合格的单例。因为 Python 的import机制保证config模块只被加载一次，所以整个进程里只有一份config实例。这种方式的好处是不需要任何修饰器、元类，代码可读性极高；坏处是它的“单例约束”是靠约定维持的：如果哪个调用方在模块里再写Config()，它就会创建一个新实例，程序不会报错，只是逻辑上不再唯一。
在团队项目里，我会把这种用法写进文档，并且在关键类上加一个注释说明“请勿直接实例化此类，请使用模块级变量”。如果你希望约束自动生效，那么继续往下看装饰器、元类那些做法。
2.2__new__方法实现：侵入类本身
最常见的“教科书式”单例实现是用__new__方法。原理很简单：当你调用Config()时，Python 会先调用cls.__new__(cls)来创建实例，再调用__init__(self)初始化实例。只要我们在__new__里控制返回的实例，就能保证Config()永远返回同一个对象。
典型代码如下：
class Singleton: _instance = None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance这段代码的实现成本极低，也容易理解，适合教学和个人项目。但说实话，它有两个明显问题。第一，它没有解决__init__重复执行的问题：你每次调用Config()，__new__返回的都是同一个实例，但 Python 仍然会在这个实例上调用一次__init__，于是retry_times、timeout这些属性会被重置成初始值。对于只读配置还好，对于带累加状态的单例来说就是灾难。第二，它没有考虑多线程并发：两个线程同时第一次调用Config()，可能同时发现_instance is None，然后各自创建实例，其中一个被丢弃，虽然不一定报错，但实例化的过程可能重复执行，如果__init__里有资源初始化操作，就会出现问题。
针对__init__重复执行，可以在__new__里配合一个标志位，或者干脆把初始化逻辑移到__new__里：
class Singleton: _instance = None _initialized = False def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance = super().__new__(cls) if not cls._initialized: cls._initialized = True # 在这里做初始化，而不是放在 __init__ cls._instance.retry_times = 3 cls._instance.timeout = 10 return cls._instance但这又会导致一个问题：如果你把这个单例当作基类，子类想通过__init__初始化自己的属性呢？牵一发动全身。所以__new__方式适合“够用就行”的项目，不适合需要被继承扩展的场景。
2.3 线程安全版本：加锁不是万能的
如果项目是多线程环境，比如 Web 服务的 Worker 处理线程、爬虫的多线程任务，你就要考虑并发场景下的单例。最简单粗暴的方法是在__new__里加一把线程锁：
import threading lock = threading.Lock() class Singleton: _instance = None def __new__(cls, *args, **kwargs): if cls._instance is None: with lock: if cls._instance is None: cls._instance = super().__new__(cls) return cls._instance这里用的是“双重检查加锁”（double-checked locking）。第一个if是为了避免不必要的加锁开销，因为一旦_instance已经存在，并发读取就是安全的。第二个if是在获得锁之后再次检查，防止两个线程同时通过了第一个检查，一个线程创建完实例释放锁后，另一个线程又去创建。这个模式在 C++/Java 里要小心内存可见性问题，但 Python 的 GIL 和对象模型保证了至少在 CPython 下这个写法是安全可靠的。
不过我要泼一盆冷水：加锁能解决实例创建阶段的并发问题，但解决不了单例实例内部状态的并发问题。如果你在__init__里修改的是共享列表、计数器，单例实现再完美，多个线程同时写这个实例的字段一样会竞争。你需要针对业务状态加锁，而不是只锁一个创建实例的过程。很多同学看到“线程安全单例”就以为万事大吉，其实真正要处理的是实例方法内部的资源竞争。
2.4 装饰器实现：不改类，很优雅
如果你不想入侵类本身的__new__方法，或者你希望同一个类在某种场景下是单例、在另一种场景下不是单例，装饰器就是个更优雅的选择。用法是写一个通用装饰器，把一个类包装成“每次调用都返回同一个实例”的形式。
from functools import wraps def singleton(cls): _instance = {} _lock = threading.Lock() @wraps(cls) def get_instance(*args, **kwargs): if cls not in _instance: with _lock: if cls not in _instance: _instance[cls] = cls(*args, **kwargs) return _instance[cls] return get_instance用的时候：
@singleton class Config: def __init__(self): self.timeout = 10这种写法最大的好处是“装饰器是用来装饰的，类本身不用改”，所以它特别适合那些“类代码不是你自己维护、但希望它在当前项目里作为单例使用”的第三方类。比如某个 SDK 里定义了APIClient，你不想动它的源码，又希望全局只创建一次连接，直接用@singleton包一层即可，非常干净。
需要注意的坑是：当你在装饰器里返回get_instance后，类的元信息（__name__、__doc__）虽然通过@wraps保留了，但Config.__class__就不再是原来的类了。如果你有代码在检查isinstance(obj, Config)，它的行为会变得捉摸不定，因为Config现在实际上是那个函数。所以装饰器版适合快速落地，但如果你高度依赖类型检查、继承或者pickle，它的水土不服会逐渐显现。
2.5 元类实现：拦截类名调用
要说最“正统”的 Python 单例实现，很多人会推荐元类方式。元区相当于“类的类”，它控制类对象如何被创建。当你定义class Config(metaclass=SingletonMeta)时，SingletonMeta就能拦截Config()的所有调用。
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: instance = super().__call__(*args, **kwargs) cls._instances[cls] = instance return cls._instances[cls]使用：
class Config(metaclass=SingletonMeta): def __init__(self): self.timeout = 10这里的关键是重写了type.__call__。正常情况下，Config()的实际流程是type.__call__(Config)，它会先调用Config.__new__再调用Config.__init__。现在元类接管了__call__，直接返回已经存在的那份实例，所以从调用方的角度来看，一切照旧，实例却是唯一的。
元类实现比__new__实现更“彻底”，因为它连创建过程都拦截了。同时它天然站在类体系的高层，对子类的影响也能统一处理。不过，元类也有一个经典坑：如果你让子类继承单例父类，且父类用了SingletonMeta，子类也会自动变成单例，但父类和子类的实例是不共享的，因为_instances是以cls为键的。这听着合理，但很多人第一次写的时候会误以为“子类调用的父类单例”，结果自查时浪费了大量时间。稍后我在第 4 小节会专门展开。
3. 实操：打造一个可靠的线程安全单例
3.1 为什么线程安全很重要
我先讲一个我第二年写 Python 时遇到的真实事故。当时公司在做一个网关服务，我用一个DeviceManager类管理所有设备连接。起初代码里只有DeviceManager()，几台设备 Demo 跑得好好的。产品上线后设备量到了一百多台，某个凌晨突然出现大量连接断开。排查时发现，原来是启动阶段多个初始化线程同时调用DeviceManager()，有的线程拿到了不同的实例，不同实例持有的连接池不一样，导致一部分连接被错误管理。后来我把所有调用点改成单例，问题立刻消失。
这个案例告诉我们：线程安全不是纸面概念，它是并发场景下的硬性要求。只要你不能保证程序的入口是单线程的，那么单例实现就必须考虑并发。特别是 Web 服务，启动时可能同时有多个 worker 在初始化同一个模块，如果没有锁，你分分钟会碰到“一个进程里有两个单例实例”这种诡异情况。
3.2 加锁实现与双重检查
现在我们把前面的方式综合起来，写一个我认为最均衡的版本：元类加双重检查锁。这个版本既能让调用方无感知，又能安全应对并发启动。
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: instance = super().__call__(*args, **kwargs) cls._instances[cls] = instance return cls._instances[cls]注意我用的是cls not in cls._instances，而不是cls._instances.get(cls) is None。这两者看起来很接近，但语义上有区别：如果某个单例实例本身是None（虽然理智情况下不会），get方式会误判；同时in判断也更直观。这是个小细节，但在排查问题是会省很多时间。
锁放在_lock上意味着所有使用这个元类的类都共享同一把锁，这会让“不同单例类首次创建”互相同步。如果每个单例的初始化都很耗时，共享锁会成为启动瓶径。这时候优化方案是“整个元类用_locks字典，按类存放锁”：
class SingletonMeta(type): _instances = {} _locks = {} def __call__(cls, *args, **kwargs): if cls not in cls._instances: if cls not in cls._locks: with SingletonMeta._class_lock: if cls not in cls._locks: cls._locks[cls] = threading.Lock() with cls._locks[cls]: if cls not in cls._instances: instance = super().__call__(*args, **kwargs) cls._instances[cls] = instance return cls._instances[cls]这段代码里我又加了一把_class_lock来保护_locks字典本身的并发写入。看起来复杂了一点，但它保证了每个单例类各自的初始化过程互不阻塞。如果你的项目里单例类很多，我建议直接使用这个版本。
3.3 防止__init__被重复执行
刚才我们在对比方案时提到，直接用元类版当你Config()时，虽然返回的是同一个实例，但如果__init__每次都执行一遍，里面的一些初始化逻辑（比如重置计数器、重新读取配置）就会重复运行。
我推荐的做法是引入一个_initialized标记，在第一次__init__执行完成后再设置。但由于元类接管了__call__，你可以不动原来的__init__，只在元类的__call__里处理标记。
不过最稳妥的思路是：单例类的__init__应该写成“幂等”的，也就是无论执行多少次，结果一致。如果你的初始化逻辑定义的是缺省值，重复执行也没事。如果初始化里有副作用（打开文件、发送请求、修改全局变量），那就要么把它搬到__new__里用_initialized标记，要么在__init__开头加一个判断：
class Config(metaclass=SingletonMeta): def __init__(self): if hasattr(self, '_initialized'): return self._initialized = True self.timeout = 10 self.retry_times = 3这个方法简单实用。你不需要理解元类怎么拦截调用，只要在类里加一个属性和一个判断，就能避免__init__重复初始化带来的副作用。如果你用的是__new__版本，同样思路也适用。
3.4 序列化、复制和内存上的坑
一个平时很隐蔽、但调试时能折腾死人的问题：单例对象被序列化或浅拷贝之后，“唯一性”被破坏。比如你有一个单例配置对象config，代码里写copy.copy(config)，得到的就不再是同一个对象，它是一个独立副本。如果你把config通过pickle保存到文件的，再 load 回来，同样也是一个新实例。
如果你的单例只是存配置，副本似乎无伤大雅。但如果单例内部持有数据库连接、线程池、文件句柄，被复制之后再关闭副本，很可能连带释放了原来的资源，或者产生不可预知的行为。
解决方案分为两步。第一步，从源头上禁止或老老实实实现：
def __copy__(self): return self def __deepcopy__(self, memo): return self def __reduce__(self): return (self.__class__, ())第二步，在团队规范里约定：不要对单例对象做copy或pickle操作，如果实在需要持久化保存数据，应当提取单例内部的可序列化字段，而不是直接保存对象。这个约定比代码防御更重要，因为代码只能防住自己，防不住别人copy.copy(config)。
内存上还有一个小坑：元类字典_instances里的实例是强引用，只要程序不结束，单例对象永远不会被垃圾回收。这听上去很合理，但如果你错误地用一个大对象作为单例，比如把整个 DataFrame 缓存下来，内存就会一直占着。单例不是内存不释放的借口，你仍然需要在不需要时显式清理。
4. 常见问题与排查技巧实录
4.1 为什么打印两次__init__，是不是写错了
新手常问：“为什么我的单例只生成了唯一实例，但每次调用都打印两次__init__？”这其实是__new__和数据模型各自机制造成的：Pythons 调用Config()时，即使__new__返回了已有实例，解释器仍然会调用__init__。所以你在__init__里打日志，每次调用都会触发，但对象地址是同一个。
排查方案很简单：打日志打印id(self)，你会发现id一致。如果想消除重复初始化，就按第 3.3 节的方法加_initialized标记。还有一种特殊情况是，当你用pickle.loads恢复对象时，它不会走__new__，而是会先创建新实例再调用__init__，这时候你再打印__init__也是正常的，但那意味着单例失效了，需要用 4.2 的方法处理。
4.2 pickle 序列化后出现两个实例
这是元类和__new__方案共有的经典问题。默认情况下，pickle会利用对象的__dict__重建实例，它不会检查你的单例逻辑。哪怕你在__new__里锁得再严实，pickle.loads出来的也是另一个对象。
解决思路是给类添加__reduce__方法，让它一定要返回当前单例：
class Config(metaclass=SingletonMeta): def __reduce__(self): return (self.__class__, ())这样pickle.dumps(config)保存的不是实例本身，而是“如何获取这个单例”的描述，load 的时候调用Config()拿回已有的单例。唯一要注意的是，这个方案要求单例类的构造参数必须能在__reduce__里完整重建。如果构造参数复杂，你可能需要稍微调整__reduce__的返回结构：返回(调用目标, 参数, 状态字典)的形式。
4.3 子类化单例的连环坑
当父类是单例，而子类想继承父类再增加一些能力时，事情就开始变得拧巴。如果你用元类实现单例，父类和子类会各自持有自己的实例，因为_instances的键是类本身。这造成一个自然结果：Parent()返回 A，Child()返回 B，两个人互不相干。这可能正是你想要的，因为不同子类代表不同配置。
但如果你写的时候不小心用了“按父类缓存”的逻辑，比如在元类里统一用base判断，就很可能让所有子类都返回同一个实例，这几乎肯定不是期望行为。我的建议是：如果真的允许子类，那单例的作用域就按具体类来区分，不要共享。如果共享才是你要的，那说明你需要的不是传统单例，而是“多实例共享同一份状态”。这种情况下，直接用MonoState（Borg）模式更合适。
4.4 依赖注入与 MonoState 作为替代
在实际项目里，全局唯一的要求往往可以换成“全局共享状态”。这就是MonoState模式，也叫 Borg 模式：它不限制实例数量，但让所有实例共享同一个__dict__。从外部看，A() is B()是 False，但A().state is B().state是 True，所有实例的状态完全一致。
class Borg: _shared_state = {} def __new__(cls, *args, **kwargs): obj = super().__new__(cls, *args, **kwargs) obj.__dict__ = cls._shared_state return obj这个模式的优势在于它规避了“实例唯一”带来的继承、序列化问题，copy.copy和pickle虽然能生产新实例，但新实例的状态也和旧实例共享，唯一性崩溃的危险几乎不存在。缺点是它没有真正的“唯一标识”，如果你依赖is判断身份，就会失望。
另一个更现代的替代就是依赖注入（Dependency Injection）。你不需要强制任何类称为单例，只在应用启动时创建一个实例，然后通过构造函数、框架容器把这个实例注入到需要它的地方。这样做的好处是测试特别顺畅，因为你可以轻松 mock 掉这个实例，而不是和全局单例较劲。我强烈建议你在设计新模块时优先考虑依赖注入，把单例作为最后的默认方案。
5. 关于单例模式，我的一些实际操作经验
写到现在，我想把个人偏好的结论放在最后顺便聊聊。如果你只是个人项目、包一层脚本，用模块级变量是最划算的，因为简单和可靠是这时候的第一优先级；如果你在写一个需要被团队长期维护的库，元类 + 锁的方式最“正经”，因为它把单例约束自动施加到所有子类上，还能配合pickle处理；如果你在改造遗留代码，不想动原来的类，装饰器版是最快的落地手段。
我还特别想强调一点：单例模式听起来很小，但它牵扯到并发、元类、序列化和测试，每一个分支都有真实的坑。很多人背一个模板就上生产，等到出问题时才意识到“单例不是写三行代码就结束的事”。我曾经维护过一个老服务，因为某个单例被copy.copy了一次，导致配置中心的热更新推不到主实例，排查了大半天。所以如果你决定用单例，请顺手把__copy__、__deepcopy__、__reduce__都考虑进去。
最后分享一个小技巧：在调试单例相关问题时，优先打印id(obj)，看它是否始终一致；然后再检查obj.__class__是否是你期望的类。这两行输出基本能帮你快速判断问题出在“实例被重建”还是“元类把类给换了”。单例模式不是银弹，但当你确实需要全局唯一资源时，选对实现方式、补上初始化保护和序列化防御，它依然是一个很值得放进工具箱的模式。
