Python：模块作用域对象的weakref.finalize未执行问题咨询

阿华AIGC实验室

2026-5-20

模块作用域对象的weakref.finalize未执行问题分析与解决

这个问题我之前也踩过坑，核心原因在于模块级别的对象在Python解释器生命周期中的特殊地位——它们会被保留到解释器退出阶段，而此时垃圾回收的执行逻辑和普通作用域对象完全不同。

为什么终结器没执行？

Python的模块对象本身会被全局的sys.modules字典持有引用，所以模块作用域的对象只要没被显式删除，其引用计数永远不会降到0。而weakref.finalize的触发依赖于对象被垃圾回收（引用计数归0或被循环垃圾回收器处理）。当解释器准备退出时，它不会按常规流程处理所有模块级对象的垃圾回收，很多时候会直接终止进程，导致终结器根本没机会运行。

哪怕你的对象没有持有活跃线程的引用，只要它在模块作用域，就会被sys.modules间接持有，这就是它没被回收的关键原因。

可行的解决方案

这里有几个实用的处理方式，比显式调用del更优雅：

避免模块级对象，改用局部/函数作用域
把对象的创建放到函数或者上下文管理器里，这样对象的生命周期被限制在特定代码块内，执行完后引用计数自然归0，终结器就能正常触发。比如：
```
def main():
    obj = YourClass()
    # 业务逻辑代码
    return

if __name__ == "__main__":
    main()
```
这样obj在main函数执行完后就会被回收，终结器正常运行。
手动触发垃圾回收（谨慎使用）
如果必须用模块级对象，可以在不再需要它的时候，先del掉，再调用gc.collect()强制触发垃圾回收：
```
import gc

# 模块级对象
obj = YourClass()

# 使用完对象后
del obj
gc.collect()  # 强制触发垃圾回收，执行终结器
```
不过这种方式还是需要手动干预，适合一些特殊场景。
结合atexit模块做退出清理
如果你的清理逻辑不依赖于对象被回收的时机，而是只要在解释器退出时执行，可以用atexit.register()注册清理函数。不过要注意，这和weakref.finalize的触发逻辑不同——atexit是不管对象是否存活都会执行：
```
import atexit

def cleanup_background_threads():
    # 你的清理逻辑，比如停止后台线程
    pass

atexit.register(cleanup_background_threads)
```
排查隐式引用
虽然你说对象没有持有活跃线程引用，但可以再用gc.get_referrers()排查下是否有其他地方偷偷持有了对象的引用：
```
import gc

print(gc.get_referrers(obj))
```
输出结果会显示所有引用该对象的地方，帮你找到隐藏的引用源。