Go sync.Once 内部再次调用自身为什么死锁

我第一次把一段“只初始化一次”的逻辑塞进 sync.Once 时，最容易忽略的不是并发，而是回调的调用边界：如果回调里又调用同一个 Once.Do，程序不会把它当成“已经完成”，而会一直等下去。原因是外层 Do 必须等回调返回后才算完成，内层调用又要等待同一个实例的执行权，两个条件互相等待，最终形成死锁。

官方文档地址：https://pkg.go.dev/sync#Once

判断这类问题只抓住一句话：Once.Do 的回调没有返回前，当前 Once 就没有完成；回调内部再次进入同一个 Once，不是快速跳过，而是等待当前调用结束。

先看一个会重入的最小写法

下面的代码把初始化函数包在闭包里，并在闭包内部重新调用同一个 once.Do。注释只标出关键边界，真正的问题是调用对象相同，不是递归深度有多大。

package main

import "sync"

func main() {
	var once sync.Once

	once.Do(func() {
		// 外层 Do 的回调尚未返回，Once 仍处于执行中。
		once.Do(func() {
			// 内层调用使用同一个 Once，无法绕过外层调用。
		})
	})
}

这里不需要再叠加第二个 goroutine 才能出现问题。只要内层调用使用的是同一个 once，重入路径就已经成立；如果外层回调还在等待某个通道或其他锁，表面上的卡点可能更远，但根因仍然是 Once 的完成条件没有满足。

为什么不会因为 done 标记而直接返回

当前 Go 的 sync.Once 同时维护完成标记和内部互斥锁。Do 先读取完成标记；未完成时进入慢路径，慢路径拿到互斥锁后执行回调，并在回调返回之后才写入完成标记。这保证了其他调用者从 Do 返回时，初始化动作已经结束。

因此，外层回调执行期间，完成标记仍不是“已完成”。内层 Do 再读到未完成，就会尝试进入同一个慢路径。可是外层调用还持有内部互斥锁，内层调用只能等待；外层又在等内层返回，于是出现自等待。

这也是为什么不能用“把完成标记提前写入”来解释或修复问题。那样虽然可能让后续调用不等待，却破坏了 Do 返回时回调已经完成的语义；官方实现把标记延迟到回调返回之后，正是为了让并发调用者看到完整初始化结果。

改法：让 Once 只负责入口，初始化函数不要反向调用它

实际项目里，我会把“只允许进入一次”和“初始化做什么”拆开。回调内部可以调用普通函数，也可以调用另一套明确不同生命周期的初始化逻辑，但不要再次进入这个同名、同实例的 Once。

package main

import "sync"

type Config struct {
	Endpoint string
}

var (
	configOnce sync.Once
	config     Config
)

func loadConfig() Config {
	// 纯初始化函数不接触 configOnce，避免形成回调回路。
	return Config{Endpoint: "https://api.example.test"}
}

func ConfigValue() Config {
	configOnce.Do(func() {
		// Once 只控制一次入口，结果由独立函数产生。
		config = loadConfig()
	})
	return config
}

这个结构的重点不是函数名，而是调用图只有一个方向：入口进入 Do，Do 调用独立初始化函数，初始化函数返回结果。读取结果的代码也不应该在初始化过程中反向触发同一个入口。

排查时记住四个边界

• 同一实例：只有再次使用同一个 Once 才是本文讨论的重入死锁；新建另一个实例是另一套生命周期。
• 回调返回：完成标记是在回调返回后才建立，不能把“已经进入回调”误认为“已经完成”。
• 隐藏回路：回调调用的辅助函数、单例 getter 或依赖注入工厂，也可能间接再调用同一个入口。
• 不要复制 Once：sync.Once 首次使用后不能复制；复制对象并不能作为解决重入的办法。

我通常先画出一条调用链，再搜索链路中是否出现同一个 Once 变量：入口 → Do → 回调 → getter/工厂 → Do。只要闭环回到了同一实例，就应该先拆分职责，而不是继续增加锁或 goroutine。

相关问题

多个 goroutine 同时调用同一个 Once 会死锁吗？

正常并发调用本身不是重入：一个调用执行回调，其他调用等待它完成，随后返回。需要重点排查的是回调执行路径是否又回到了同一个 Once。

回调发生 panic 后还能再次初始化吗？

不能把 panic 当成“下次重试”的信号。当前文档规定，函数发生 panic 时，Once 认为该调用已经返回，后续调用不会再次执行该函数；如果业务需要重试语义，应把重试状态设计在 Once 之外。

小结

sync.Once 解决的是“某个动作只成功进入一次，并且调用返回时动作已经结束”。它不是可重入锁，也不会在回调尚未返回时提前把自己标记为完成。看到内部再次调用自身时，沿着同一个实例的调用链拆开初始化职责，通常就是最短、最清楚的修复路径。