Go strings.Builder 为什么复制后继续写会 panic

strings.Builder 在第一次写入后会记住自己的地址。把这个已经使用过的 Builder 按值复制，新副本会带着原对象的地址记录；当副本再次调用 Write、WriteString、WriteByte、WriteRune 或 Grow 时，内部 copyCheck 发现“记录地址不是当前接收者地址”，于是触发 strings: illegal use of non-zero Builder copied by value。这不是容量不足，而是标准库主动阻止不安全的值复制。

Go 官方文档：https://pkg.go.dev/strings#Builder

现象：复制看起来成功，继续写才 panic

最容易复现的场景是先写入，再做普通赋值。赋值本身不会报错，读取副本的长度或字符串也可能暂时看不出异常；真正的保护检查位于写方法和 Grow 中，因此通常到下一次修改才 panic。

package main

import "strings"

func main() {
	var original strings.Builder
	// 第一次写入后，Builder 已经成为非零值并记录自身地址
	original.WriteString("order=")

	// 错误：按值复制已经使用过的 Builder
	copied := original

	// 副本再次写入时会触发 copyCheck 的地址检查
	copied.WriteString("A-100")
}

panic 文本里的重点是 non-zero Builder copied by value。如果看到这段信息，不要先去调 Grow 容量，也不要用 recover 吞掉异常；真正要找的是复制发生在哪里。

分层检查：复制点不一定是直接赋值

第一层先查显式复制：变量赋值、函数按值参数、函数按值返回。第二层再查间接复制：Builder 作为结构体字段时复制整个结构体，把结构体追加到值切片，或把它赋给接口。只要复制发生时 Builder 已经写过内容，就违反了“非零 Builder 不得复制”的公开约定。

按值传参是最常见的隐藏复制

func appendSuffix(b strings.Builder, suffix string) {
	// 错误：形参 b 是实参的值副本，继续写会 panic
	b.WriteString(suffix)
}

func buildName() string {
	var b strings.Builder
	b.WriteString("report")
	appendSuffix(b, ".csv")
	return b.String()
}

方法使用指针接收者并不意味着所有调用都会自动安全。如果 Builder 先被复制进另一个变量或外层结构体，再通过自动取地址调用方法，接收者仍然是那个非法副本。

证据判断：copyCheck 在比较什么

当前标准库实现中，Builder 内部有一个用于检测值复制的 addr 指针和一个字节缓冲区 buf。第一次修改时，copyCheck 把 addr 记录为当前 Builder 自身地址。按值复制会复制这个地址字段，却不会让它自动改成新对象地址。

副本调用写方法时，检查条件相当于“addr 已设置，并且 addr != 当前接收者”。不一致就 panic。这个保护很必要，因为 Builder 为了减少字符串构建中的内存复制，会让 String() 结果与内部缓冲区存在紧密关系；允许多个值副本继续修改会破坏其内存语义。

String() 本身不执行这项写入检查，所以非法副本有时还能读取出内容。这不代表复制有效，也不应把“只读暂时没 panic”当成可以继续使用的依据。官方 API 约定已经明确：不要复制非零 Builder。

修复动作：让 Builder 只有一个所有者

最直接的修复是把 Builder 创建在最终负责构建字符串的函数里，其他辅助函数只接收指针。这样所有写入都落到同一个对象，不会产生值副本。

package main

import "strings"

func appendField(b *strings.Builder, key, value string) {
	// 指针参数始终指向调用者持有的同一个 Builder
	b.WriteString(key)
	b.WriteByte('=')
	b.WriteString(value)
}

func buildQuery() string {
	var b strings.Builder
	// 可选：提前估算容量，但不改变 Builder 的所有权
	b.Grow(32)

	appendField(&b, "user", "alice")
	b.WriteByte('&')
	appendField(&b, "state", "active")

	// 跨函数边界返回最终字符串，而不是返回 Builder 值
	return b.String()
}

结构体里包含 Builder 时要约束整个结构体

把 Builder 放进结构体并不会自动消除问题。结构体实例一旦开始写入 Builder，就不应再按值复制。方法统一使用指针接收者，集合里存指针，构造函数也返回指针，可以让所有权更清晰。

type Message struct {
	body strings.Builder
}

func NewMessage() *Message {
	// 返回指针，避免构建过程中复制整个结构体
	return &Message{}
}

func (m *Message) Add(text string) {
	// 指针接收者修改同一个结构体中的 Builder
	m.body.WriteString(text)
}

func (m *Message) String() string {
	// 对外只暴露最终字符串结果
	return m.body.String()
}

如果业务确实要复制“当前内容”，应复制字符串结果，再用一个全新的零值 Builder 继续构建，而不是复制 Builder 本身。

func branchText(source *strings.Builder, suffix string) string {
	// 先取得不可变字符串快照，不复制 Builder
	base := source.String()

	var next strings.Builder
	// 新 Builder 独立拥有自己的状态和缓冲区
	next.Grow(len(base) + len(suffix))
	next.WriteString(base)
	next.WriteString(suffix)
	return next.String()
}

反向验证：证明修复的是复制问题

修复后应写一个最小测试，覆盖辅助函数多次写入、最终字符串和连续调用。测试不需要断言内部地址，只要确认整个构建过程没有 panic，结果也符合预期即可。

package textbuild

import (
	"strings"
	"testing"
)

func TestAppendFieldUsesSameBuilder(t *testing.T) {
	var b strings.Builder

	// 两次调用都把同一个 Builder 指针传给辅助函数
	appendField(&b, "id", "42")
	b.WriteByte('&')
	appendField(&b, "page", "3")

	// 同时验证无 panic 与最终字符串内容
	if got, want := b.String(), "id=42&page=3"; got != want {
		t.Fatalf("got %q, want %q", got, want)
	}
}

如果测试仍然 panic，继续沿调用链检查外层对象：测试表是否按值保存含 Builder 的结构体、辅助函数是否返回 Builder、是否把对象追加到 []Message 后又继续写。panic 的位置是“发现复制”的写入点，不一定是“发生复制”的那一行。

最终检查清单

• Builder 第一次写入后，不再做变量赋值或整体结构体复制。
• 写入辅助函数接收 *strings.Builder，而不是 strings.Builder。
• 构建函数返回 string，不返回已使用的 Builder 值。
• 需要分支内容时，读取 String()，再创建一个新的零值 Builder。
• Reset() 用于同一所有者复用 Builder，不用于为非法副本“洗白”。
• 不要用 recover 掩盖 panic；应删除复制路径。

相关问题

复制零值 Builder 也会 panic 吗？

官方限制的是非零 Builder。尚未使用的零值没有绑定地址，分别首次写入时可以各自建立状态。但这种写法很容易因重构把第一次写入移到复制之前，工程上更清晰的做法仍是分别声明零值，不复制 Builder。

调用 String 后还能继续写原 Builder 吗？

可以继续写原来的 Builder；问题在于复制 Builder 值，而不是调用 String()。已经取得的字符串应视为只读结果。

Reset 后可以复制 Builder 吗？

不要把 Reset 当成复制方案。它用于清空同一个 Builder。需要新构建器时，直接声明新的零值更符合 API 约定，也不会依赖内部实现细节。

把 Builder 放进 sync.Pool 能解决吗？

sync.Pool 解决的是对象复用，不会自动修复值复制。即便放入池中，也应存取指针、明确单一借用者，并在归还前由同一所有者重置。

总结：strings.Builder 的 panic 是复制保护在生效。首次写入后的 Builder 已经绑定自身地址，值复制会留下指向原对象的地址记录，副本再次修改时被 copyCheck 拒绝。沿直接赋值、按值参数、按值返回和外层结构体复制逐层检查，把写入改成指针协作，并只传递最终字符串，就能从根源上消除问题。