复制含 Mutex 的结构体为什么会破坏锁状态

如果一个结构体里嵌有 sync.Mutex，它在首次使用后就不能再按值复制。复制动作会把锁字段当前的内部状态和业务字段一起复制到新对象，但新对象并不会与原对象共享同一把锁。结果可能是两个 goroutine 分别拿着两份锁访问同一份外部资源，也可能是副本带着“已加锁”的状态，却再也等不到对应的解锁。

官方地址：https://pkg.go.dev/sync#Mutex

排查这类问题时，先找“值复制”路径，再把含锁类型改成指针语义；不要试图手动重置 Mutex，也不要用加更多锁来掩盖复制。

哪些信号说明锁可能被复制了

值复制通常不会在编译阶段直接报错，现场表现反而容易被误认为是普通的数据竞争。可以先对照下面几种信号：

• 方法里明明调用了 Lock 和 Unlock，并发计数仍然出现丢失或顺序异常。
• 某个值接收者方法运行后，调用方看到的计数字段没有变化，因为整个接收者已经是副本。
• 复制发生在加锁之后，副本保留了旧的锁状态，后续对副本加锁可能长时间阻塞。
• go vet 报告 copylocks，提示函数参数、接收者、返回值或循环变量复制了含锁值。

先记住一个判断原则：锁保护的是具体的内存对象，而不是类型名称。即使两个对象的类型都是同一个结构体，只要它们各自持有一份 Mutex，它们就不会自动互斥。

为什么一次赋值会变成两把互不协调的锁

Go 的结构体赋值是值复制。假设类型如下：

type Counter struct {
	mu sync.Mutex
	n  int
}

// 复制会同时复制业务字段和 Mutex 字段。
copyOf := original

copyOf 不是指向 original 的别名，而是另一份结构体。n 有了自己的副本，mu 也有了自己的副本。两个 goroutine 如果分别对 original.mu 和 copyOf.mu 加锁，锁之间没有任何同步关系，保护范围也就被拆开了。

更危险的情况是复制发生在锁已经使用之后。官方文档明确规定，Mutex 在首次使用后不能复制。此时副本可能带着原对象当时的锁状态、等待信息或运行时关联状态；这些状态不应被当成一个可安全拷贝的普通字段。具体内部布局不属于业务代码可以依赖的契约，排查时只需要遵守“不复制已使用的 Mutex”这一规则。

值接收者为什么会悄悄复制整个结构体

下面的方法看起来给计数加了锁，但接收者写成了值类型：

type Counter struct {
	mu sync.Mutex
	n  int
}

// 错误示例：值接收者会复制 Counter，包括其中的 Mutex。
func (c Counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock()
	// 这里修改的是接收者副本的 n，不是调用方持有的 n。
	c.n += delta
}

// 这里的 c 会被按值传入，调用方的计数不会按预期更新。
func useCounter(c Counter) {
	c.Add(1)
}

这个例子有两个问题：每次调用 Add 都可能复制一个锁；同时 n 也在副本中修改。它不是“锁粒度不够”，而是方法根本没有操作调用方的那个对象。

排查复制入口：参数、返回值和 range 都要看

定位时可以从所有会产生隐式或显式值复制的地方开始。下面这些写法都应该优先改成指针语义：

// 这些签名都会让含锁值发生按值传递或返回。
func consume(c Counter) Counter { // 值参数和返回值都可能复制锁。
	return c
}

func (c Counter) Snapshot() int { // 值接收者复制整个 Counter。
	return c.n
}

func walk(items []Counter) {
	for _, item := range items {
		// range 变量 item 是元素的值副本，不能把它当成原对象加锁。
		item.Add(1)
	}
}

还要检查显式赋值、结构体返回、把值放进接口、把含锁结构体当作 map 的值读取，以及会复制元素的容器操作。并不是每个复制都会立刻制造可见故障，但它们都让类型的生命周期变得难以推断。若对象需要并发使用，优先让所有权和访问路径都指向同一地址。

修复方式：用指针接收者让调用方回到同一对象

推荐的改法是让构造函数返回指针，方法使用指针接收者，函数参数也使用指针：

package main

import (
	"fmt"
	"sync"
)

type Counter struct {
	mu sync.Mutex
	n  int
}

// 指针接收者保证加锁和修改都发生在调用方持有的 Counter 上。
func (c *Counter) Add(delta int) {
	c.mu.Lock()
	defer c.mu.Unlock()
	// 只在临界区修改共享字段，避免读取和写入分散到不同对象。
	c.n += delta
}

// 指针参数避免把含锁对象复制进函数。
func addOne(c *Counter) {
	c.Add(1)
}

func main() {
	// 零值 Counter 可以直接使用，但后续只通过同一个指针访问。
	c := &Counter{}
	addOne(c)
	c.Add(2)
	fmt.Println(c.n)
}

如果确实需要返回只读结果，返回普通的 int、字符串或不含锁的快照数据即可，不要把带有原始 Mutex 的结构体整体返回。快照方法本身也应使用指针接收者，并在锁内读取字段：

// 返回基础类型快照，避免把内部 Mutex 暴露给调用方。
func (c *Counter) Value() int {
	c.mu.Lock()
	defer c.mu.Unlock()
	return c.n
}

复制已经发生时怎么回退

如果问题已经出现在代码中，先暂停继续扩大复制范围，再按对象生命周期处理：

1. 把值接收者、值参数和含锁返回值改成指针形式，统一调用方的对象地址。
2. 检查容器遍历，把需要修改或加锁的元素改成索引访问，避免把元素复制到 range 变量。
3. 不要对已经使用过的 Mutex 做“解锁后再复制”或手动清零；如果必须重新开始，创建一个全新的业务对象。
4. 让旧对象停止接收新请求后，再切换到新对象；不要在并发访问仍未结束时直接替换指针指向。

如果副本曾经带着锁状态进入线上流程，恢复动作应优先保证请求不再进入这条复制路径。手动调用 Unlock 试图“解冻”未知状态并不安全，因为你无法确认这份锁状态是否对应当前 goroutine 或当前对象的真实访问关系。

用 go vet 把 copylocks 变成发布前检查

Go 工具链的 copylocks 分析器会检查把锁按值传递的常见路径。它不是运行时锁证明，但非常适合在代码审查和发布前提前发现问题：

# 扫描当前模块，重点关注含 Mutex 的值参数、接收者和赋值。
go vet ./...

# 只检查指定包，便于先定位刚修改的并发组件。
go vet ./internal/counter

看到类似“passes lock by value”或“copies lock value”时，不要只给这一行加注释压掉告警。先确认复制发生在哪个边界，再改成指针，或者把返回结果收窄为不含锁的值。只有在确定某个类型从未包含同步原语、且误报有明确原因时，才考虑局部处理。

回归检查清单

可以把这次排障压缩成一句话：含 Mutex 的结构体要按地址共享，不要按值搬运；发现 copylocks 时修复复制边界，而不是重置锁状态。

相关问题

只复制一个从未加锁的 Mutex 可以吗？

从零值复制在某些初始化阶段看似可行，但一旦类型约定会被并发使用，就很难保证复制发生在首次使用之前。更稳妥的设计是从一开始就使用指针，避免让调用方依赖这个时间窗口。

把 Mutex 放在指针字段里能解决复制吗？

如果复制结构体时复制的是同一个 *sync.Mutex，两个结构体可能共享锁，但这会把共享关系藏在字段里，容易让数据字段和锁的保护范围不一致。除非共享所有权是明确设计，否则优先整体传递结构体指针。

sync.RWMutex 和 WaitGroup 也有同样问题吗？

有。同步原语通常都要求首次使用后不能复制。检查到 RWMutex、WaitGroup、Once 或 Cond 被按值传递时，应采用同样的指针化和生命周期检查。