Go runtime.SetFinalizer 遇到引用环时为什么不执行

我排查过一类很容易误判的 Go 问题：业务变量已经置空，runtime.SetFinalizer 注册的函数却迟迟没有输出。先说结论：如果带终结器的对象仍能沿着字段、容器或闭包形成一条路径回到自己，Go 就无法保证这组对象被回收，也无法保证终结器执行。这个限制不是 runtime.GC() 调用次数不够，而是引用关系本身没有可满足的终结顺序。

为什么引用环会让终结器失去执行条件

Go 的垃圾回收判断的是可达性。变量不再指向对象，只能说明外部入口消失了；如果对象内部还有 self、父子对象互相持有，或者一个字段间接回到了起点，GC 仍然要处理这张内部对象图。

终结器又多了一层约束：它不是简单地“发现对象不可达就调用函数”。当对象 A 指向对象 B 且两者都有终结器时，运行时需要先安排 A，再让 B 在后续阶段获得终结机会。引用环中不存在能满足所有依赖的第一节点，所以官方文档明确规定：包含带终结器对象的循环结构，不保证被回收，终结器也不保证执行。

先用一个最小对象图确认问题

排查时我会先把业务对象缩成一个带自引用的结构体，再用 channel 等待结果。这里的重点不是证明每次都超时，而是让测试明确表达“执行不保证”，避免把一次成功当成契约。

package main

import (
    "fmt"
    "runtime"
    "time"
)

type node struct {
    self *node // 自引用让对象可以从内部路径回到自己
}

func main() {
    done := make(chan struct{})
    n := &node{}
    n.self = n // 形成最小引用环
    runtime.SetFinalizer(n, func(*node) {
        close(done) // 这里只做观察，不承担真实资源释放
    })
    n = nil

    runtime.GC() // 只请求 GC；不代表 finalizer 已经执行
    select {
    case 

这段代码里，n = nil 只删除了外部变量，n.self 仍然指回同一个对象。即使把等待时间加长，也不能把“本次没收到信号”修成 runtime 的 bug。测试还要注意：runtime.GC() 不等待所有终结器真正执行，终结器由运行时的单独 goroutine 串行处理。

怎么改：断开环并把释放主路径改成显式 Close

如果对象包着文件描述符、C 内存、mmap 或其他非内存资源，最稳妥的主路径是显式释放。让拥有者提供幂等的 Close，在业务生命周期结束时调用；终结器只在调用方遗漏时做尽力而为的兜底。

type resourceOwner struct {
    handle *handle
    parent *resourceOwner
}

func (o *resourceOwner) Close() error {
    if o == nil || o.handle == nil {
        return nil // Close 设计为可重复调用，避免清理路径再次制造错误
    }
    h := o.handle
    o.handle = nil
    o.parent = nil // 先断开回指，避免对象图继续形成环
    return h.Close()
}

func newOwner(h *handle) *resourceOwner {
    o := &resourceOwner{handle: h}
    runtime.SetFinalizer(o, func(v *resourceOwner) {
        _ = v.Close() // 仅作遗漏兜底；生产代码仍应显式调用 Close
    })
    return o
}

示例中的 handle 代表资源句柄，省略了它的具体实现。真实项目还要根据并发模型给 Close 加锁或使用原子状态，并在显式关闭后调用 runtime.SetFinalizer(o, nil) 清掉终结器。若终结器闭包直接捕获 o，又会把对象重新连回清理函数，必须改为只传递不包含对象本身的资源信息。

排查时哪些现象不能当成保证

我通常按下面的清单复查，而不是继续增加 runtime.GC() 调用：

• 看对象的所有字段和容器成员，尤其是 parent、owner、缓存和闭包捕获，确认没有回指。
• 资源仍被系统调用使用时，用 runtime.KeepAlive(obj) 把对象保持到最后一次使用之后，避免终结器过早运行。
• 测试用 channel 或明确状态等待终结器完成；不要仅以 GC() 返回作为完成信号。
• 不要依赖进程退出前执行终结器，也不要让一个耗时终结器阻塞其他终结器。
• 链式对象带终结器时，释放可能跨多个 GC 周期；资源释放最好改成调用方可见的生命周期操作。

如果只是想观察对象死亡，测试可以把信号通道注入终结器，并把超时标记为“未观察到”，而不是断言“一定执行”。这能把实现细节和业务契约分开，也能避免在不同 GC 压力下出现假稳定。

常见问题

调用 runtime.SetFinalizer(nil) 能修复引用环吗？

它只能清除当前对象的终结器，不能替你断开对象之间的字段引用。需要先从业务结构上解除回指，再决定是否保留兜底机制。

为什么没有引用环，终结器仍然不执行？

终结器执行时间本来就是任意的，程序退出前也不保证执行；零大小对象、包级初始化对象以及某些微小对象批量分配也有额外限制。

Go 里应该优先使用 finalizer 还是 cleanup？

新代码通常应优先考虑显式释放；需要 GC 兜底时可评估较新的 runtime.AddCleanup。无论使用哪种机制，都不能让清理函数或参数重新持有被清理对象。