Go sync.Once 被卡住时怎么定位初始化函数里的阻塞

服务启动后，所有请求都停在同一个 once.Do(init) 附近，通常不是 sync.Once “失效”，而是第一次进入的初始化函数还没有返回。后续调用会等待这个完成边界；如果初始化函数在读 channel、抢锁或访问外部服务时没有退出条件，等待就会被放大成整条请求链的超时。

先确认卡住的是初始化函数，不是业务代码

Do 的语义很简单：第一次调用执行 f，但任何一次 Do 都要等这次 f 返回后才返回。因此看到多个请求同时等待时，先把调用链缩成三个节点：请求入口、once.Do、初始化函数。不要先把问题归因于锁竞争或网络慢。

可以给初始化函数加成对的边界日志。进入日志只打印实例标识，关键资源调用前后再打印一个短标签，退出日志必须放在初始化函数最外层的 defer 中。这样日志里只有进入没有退出，就能把排查范围收敛到初始化函数内部。

用 goroutine 栈定位 channel、锁和外部 I/O

当服务已经卡住时，最有价值的证据是 goroutine 栈，而不是继续增加重试次数。若栈停在 ，检查谁负责发送；若停在 Mutex.Lock，检查锁的持有者是否也等待初始化结果；若停在 HTTP 或数据库调用，检查请求是否带有超时。

func (c *Config) init(ctx context.Context) error {
	// 进入和退出成对出现，便于确认初始化函数是否真正返回。
	log.Printf("config init enter")
	defer log.Printf("config init leave")

	// 外部依赖必须绑定调用方的截止时间，不能无限等待。
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.endpoint, nil)
	if err != nil {
		return err
	}
	resp, err := c.client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close() // 释放响应体，避免失败路径泄漏连接。
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("config endpoint status: %s", resp.Status)
	}
	return json.NewDecoder(resp.Body).Decode(&c.value)
}

排查时把调用栈和边界日志对齐：初始化 goroutine 是“根”，其他 goroutine 若都停在同一条 once.Do 上，只说明它们在等根返回。若根又等待一个由后续请求触发的 channel 或锁，就形成了闭环，应先拆掉这个依赖，而不是把 Once 换成更大的锁。

重点排除三类会永远等不到返回的写法

其中重入最容易被误判。官方文档明确说明，如果 f 导致同一个 Do 再次调用，就会死锁。另一个边界是复制：Once 首次使用后不能复制，否则复制出来的同步状态无法表达原对象的等待关系。把它放进会被值接收者复制的结构体或作为返回值传递，都值得优先检查。

初始化失败后不要直接清零 Once

Do 的设计目标是一次性动作，不提供公开的 reset。初始化函数发生 panic 后，后续对同一 Once 的调用不会再次执行函数；这和“函数返回错误后允许自动重试”是两种不同的产品语义。

如果配置加载确实需要重试，建议把重试放在明确的状态对象中：状态对象负责记录 未开始、进行中、成功、失败，每次尝试使用新的带超时上下文，并把错误返回给调用方。若只是想在测试中重新初始化，则创建新的拥有者对象，让新的 Once 随对象一起诞生；不要并发修改内部字段，也不要把旧 Once 强制清零。

相关问题

为什么后续调用也像被锁住？

因为它们要等第一次执行的初始化函数返回。先看第一个进入者的栈。

给初始化函数加 goroutine 能解决卡住吗？

不能自动解决。它可能让 Do 更快返回，却把尚未完成的初始化状态暴露给业务；只有在明确设计异步就绪协议时才适用。

初始化函数 panic 后能否自动再试？

同一个 sync.Once 不会再次调用函数。需要重试时使用显式状态机或新的拥有者对象。

排障的顺序可以固定为：先确认唯一的 once.Do，再抓初始化 goroutine 栈，接着查资源闭环和 deadline，最后才决定是否改成可重试的状态模型。这样既保留了一次性初始化的同步保证，也不会把一个未返回的外部依赖伪装成并发原语故障。