当前位置：首页 > 文章列表 > Golang > Go问答 > Go runtime.AddCleanup 与 SetFinalizer 有什么区别

Go runtime.AddCleanup 与 SetFinalizer 有什么区别

来源：17golang原创 2026-10-05 05:28:58 0浏览收藏

维护一段旧 Go 代码时，我最容易误判的一件事，是把 runtime.SetFinalizer 和 Go 1.24 引入的 runtime.AddCleanup 当成同一个 API 的新旧写法。它们都在对象变得不可达后做兜底清理，但绑定对象的方式、回调拿到的参数、循环引用的风险和可取消能力并不一样。

官方资料：https://pkg.go.dev/runtime

新代码通常优先选 AddCleanup；旧代码迁移时要重新检查对象约束和回调是否反向持有对象。无论选哪一个，都不要把它当成进程退出前必然执行的业务清理机制，文件、连接和事务仍应由显式 Close、Release 或提交逻辑负责。

要点速览

AddCleanup 把“要观察的指针”和“要传给清理函数的资源参数”分开，约束更少，还能拿到 Cleanup 句柄取消。
SetFinalizer 的回调接收对象本身；对象会因 finalizer 暂时重新可达，依赖顺序和循环引用更容易拖住回收。
两者都是 GC 兜底，不保证退出前执行；确定的资源生命周期应保留显式释放路径。

先把两种机制放回同一张资源关系图

先看 API 的数据形状。AddCleanup(ptr, cleanup, arg) 观察的是 ptr，回调收到的是独立的 arg；典型场景是 Go 对象包着文件描述符，清理函数只拿描述符去释放外部资源。一个对象还可以挂多个 cleanup，甚至可以把 cleanup 绑定到同一块分配中的内部指针。

SetFinalizer(obj, finalizer) 则把 finalizer 直接挂到对象上，回调参数就是该对象。运行时发现对象不可达后会清除关联并在独立 goroutine 中调用 finalizer；对象在这次调用中重新变得可达，之后还要再次不可达才可能被释放。

Go runtime.AddCleanup 与 SetFinalizer 的对象、外部资源、cleanup 参数和 finalizer 回调边界说明图 — 图1：Go 资源清理关系说明图，展示 AddCleanup 与 SetFinalizer 的对象边界，不是截图或运行证据。

这就是两者最值得记住的差异：AddCleanup 可以让回调只捕获资源句柄，避免回调参数本身把对象重新连回来；SetFinalizer 天然把对象交给回调，设计不慎就会延长对象图的生命周期。

真正影响选择的是对象约束与清理时机

比较项	AddCleanup	SetFinalizer
回调参数	独立的 `arg`，类型由泛型推导	对象本身，类型必须能接收 `obj`
同一对象	可绑定多个 cleanup	通常只有一个 finalizer 关联
关系图	不指定 cleanup 顺序，可并发；循环结构通常不会像 finalizer 那样形成依赖顺序	按依赖顺序处理，循环结构可能无法保证回收
人工取消	返回 `Cleanup`，可在入队前调用 `Stop`	用 `SetFinalizer(obj, nil)` 清除关联
版本	Go 1.24 起	较早版本已有

这里有一个常见坑：Cleanup.Stop 不是“保证清理函数永远不执行”的全局开关。如果指针已经不可达，cleanup 已经入队，Stop 不再生效；想保证取消成功，必须让传给 AddCleanup 的指针在调用 Stop 期间仍然可达。

两种回调都要注意 KeepAlive。如果对象最后一次被编译器认为使用的位置早于底层系统调用，GC 可能提前让它不可达；把对象传给 runtime.KeepAlive，可以把“至少活到这里”写清楚。这个判断解决的是过早回收，不是让回调变成同步释放。

Go finalizer 依赖顺序与 cleanup 并发无序、KeepAlive 和退出边界的结构说明图 — 图2：finalizer 与 cleanup 的约束边界结构图，展示顺序、并发和退出保证的差异。

迁移时按资源生命周期做决定

如果是在 Go 1.24 以上写新的包装类型，我会把“显式释放”放在主路径，再用 AddCleanup 做兜底。例如回调只接收资源标识，不把包装对象塞进参数：

type Handle struct {
	resourceID int64
}

func attachCleanup(h *Handle, id int64) runtime.Cleanup {
	return runtime.AddCleanup(h, func(resourceID int64) {
		// 兜底释放外部资源；业务成功路径仍应主动调用 Release。
		releaseExternalResource(resourceID)
	}, id)
}

func useHandle(h *Handle) {
	// 这里执行确定的业务操作和显式释放，不等待 GC。
	defer releaseExternalResource(h.resourceID)
	// 使用 h.resourceID 完成一次受控操作。
	runtime.KeepAlive(h)
}

这段示例表达的是结构，不代表应该把释放函数复制到生产项目：如果 Release 会被显式路径和 cleanup 同时调用，就要让释放动作具备幂等性，或在显式释放后及时调用句柄的 Stop。相反，只有在维护旧版本兼容代码、确实需要对象本身参与清理时，才继续保留 SetFinalizer，并检查回调是否反向引用对象。