Go strings.Builder 为什么不能复制：传值参数、append 和 panic 的边界

一段日志拼接代码把 strings.Builder 放进结构体后，又把结构体按值传给了辅助函数。测试数据量小的时候跑着完全正常，某次追加长文本却突然弹出 “illegal use of non-zero Builder copied by value” 报错。这不是 Builder 本身的写入逻辑写错了，而是它的零值可以直接拿来写内容，一旦已经写入过数据，就不能像普通小结构体那样随手直接拷贝。

Builder 初始化后要沿着同一份实例连续写入：要么传 *strings.Builder 指针，要么在边界处只往外传已经拼好的 string。需要独立的拼接空间时，直接新声明一个零值 Builder 就行，不要拷贝已经写入过内容的 Builder。

为什么普通传值会踩到 Builder 的边界

Go 所有参数传递都是值拷贝，普通整型、体量很小的配置结构体这么传完全没问题，但 strings.Builder 内部存着已经分配好的字节缓冲区，还加了状态自检逻辑。要是它已经写入过内容之后再被拷贝，两个看起来完全独立的变量，暗地里会打破 Builder 对「同一份实例」的状态校验，下次尝试写入的时候就会主动抛 panic 终止程序。

func addSuffix(b strings.Builder) {
    b.WriteString("-done")
}

func main() {
    var b strings.Builder
    b.WriteString("job")
    addSuffix(b) // 下一次写入会触发 panic
}

容易踩坑的场景远不止函数传参这一种。写 next := b 直接赋值、把已经写过内容的 Builder 塞进切片、按值返回包含 Builder 的结构体，本质都是同一类问题。编译器不会自动帮你把这些拷贝改成指针传递，代码评审的时候要专门留意这类写法。

需要继续拼接时传指针

辅助函数的职责如果就是要往 Builder 里追加文本，参数直接声明成指针最清晰明了。调用者扫一眼就知道这个函数会修改原对象的内容，完全不会触发非零状态 Builder 的拷贝问题。

func addSuffix(b *strings.Builder) {
    b.WriteString("-done")
}

func main() {
    var b strings.Builder
    b.WriteString("job")
    addSuffix(&b)
    fmt.Println(b.String()) // job-done
}

跨函数边界时优先交付 string

很多函数根本不需要继续往 Builder 里写内容，只是要把已经拼好的结果交给日志组件、HTTP 响应或者模板渲染。这种场景下返回 b.String() 比直接返回 Builder 要合适得多：调用方拿到的是明确的最终文本，没有共享可变状态，也不会把 Builder 的特殊使用规则扩散到其他依赖包里。

func buildTitle(name string) string {
    var b strings.Builder
    b.Grow(len(name) + 7)
    b.WriteString("hello, ")
    b.WriteString(name)
    return b.String()
}

如果确实要在多个步骤之间暂时存下「还没拼接完的中间内容」，全程持有 *strings.Builder 指针就好。不要为了少写一个取地址符，把 Builder 藏进按值拷贝的 DTO 或者普通配置对象里。

从 panic 回到可验证的重构

碰到这个报错的时候，先顺着回溯最后一次 WriteString 执行之前的拷贝位置，别死盯着报错那一行找问题。需要写入内容的函数直接改成收指针，只需要读结果的函数改成收 string。改完补个简单的单元测试，覆盖「先写入一段内容，再把 Builder 丢进辅助函数」的执行路径就行。

1. 全局搜代码里所有把 Builder 当函数参数、直接给结构体赋值、塞进切片或者当返回值返回的位置。
2. 确认这个位置之前有没有触发过 Write、Grow 操作，或者 Reset 之后的再次写入。
3. 后续还要继续写入就改成传指针，只需要读最终内容就改成传 string。
4. 并发场景拆成每个子任务各自拼接自己的字符串，最后统一在单条逻辑里汇总结果。

相关问题

Builder 和 bytes.Buffer 的复制规则一样吗？

这两个都不能当成随便拷贝的通用容器。两者的官方文档约束细节不一样，但所有带内部动态缓冲区的类型，最稳妥的默认处理方式永远是传指针，或者直接传最终生成的原始数据。

Reset 后能不能复制 Builder？

别把 Reset 当成解除拷贝限制的奇技淫巧。需要一块全新的拼接空间的时候，直接新声明一个零值 Builder 可读性更高，也不会让后续维护的人搞不懂这个对象的生命周期逻辑。

可以把 Builder 放进 sync.Pool 复用吗？

可以考虑复用，但取出、使用、归还的全流程必须由单条调用链独占。用完归还之前先调用 Reset 清空内容，归还之后绝对不能再保留或者拷贝它的引用。

什么时候应该直接用加号拼接字符串？

拼接少量固定片段直接用加号写起来更清楚自然。循环里要拼大量片段、提前知道总长度想要预分配容量的场景，用 Builder 的意图和性能收益会更明显。

收尾：让 Builder 留在它的构造边界里

Builder 的核心价值是减少不必要的内存拷贝，不是让你把可变缓冲区随便到处传。需要持续写入就传指针，跨模块跨函数边界交付结果就直接传 string；把这条边界规则理清楚之后，非零值拷贝引发的 panic 基本不会再冒出来。