Go strings.Builder 为什么不能复制：零值、指针接收者与别名风险

有一段拼接逻辑在测试环境运行正常，换到线上后却在日志里看到 strings: illegal use of non-zero Builder copied by value。问题通常不是 Builder 不能用，而是它已经写入内容后又被值复制了。strings.Builder 的零值可以直接使用，但一旦开始写入，就应该把它当成不可复制的工作对象。

strings.Builder 的正确习惯是：声明后直接使用，传参用指针，写入完成后取出字符串；不要把已经写入过的 Builder 赋值给另一个 Builder，也不要把它放进会发生值复制的结构操作里。

先看清 strings.Builder 的两个使用阶段

strings.Builder 有一个容易被忽视的边界：写入前，它只是一个可直接使用的零值；写入后，它内部已经关联了用于保存字符串的状态。下面这段代码不需要 New，也不需要预分配。

package main

import (
    "fmt"
    "strings"
)

func main() {
    var b strings.Builder
    b.WriteString("order=")
    b.WriteString("2048")
    fmt.Println(b.String())
}

这里的结果是 order=2048。把变量声明为零值而不是指针并没有问题，关键在于后续是否发生了复制，以及写入是否由同一个 Builder 完成。

为什么写入后复制会在下一次操作时报错

常见误写看起来很普通：

var original strings.Builder
original.WriteString("prefix=")

copied := original
copied.WriteString("value") // 可能触发 illegal use of non-zero Builder copied by value

copied := original 是 Go 的普通值复制。它复制的不是“当前字符串的一个独立快照”，而是 Builder 当前持有的内部状态。标准库会在后续写操作中检查这种复制，避免两个 Builder 继续共享同一片内部存储。

因此，报错点经常出现在第二次 WriteString，而不是赋值语句。看到这个现象时，先沿着调用链找值复制位置，不要只在报错行附近增加锁或重新初始化。

函数传参时用指针，避免悄悄复制

如果一个辅助函数要继续写入 Builder，参数必须是指针：

func appendOrder(b *strings.Builder, id int, status string) {
    b.WriteString("id=")
    b.WriteString(strconv.Itoa(id))
    b.WriteString(" status=")
    b.WriteString(status)
}

调用时传入 &b，辅助函数改动的仍是原对象。完整示例还需要导入 strconv：

func formatOrder(id int, status string) string {
    var b strings.Builder
    appendOrder(&b, id, status)
    return b.String()
}

反过来写成 func appendOrder(b strings.Builder, ...)，即使编译通过，也会让函数拿到一个 Builder 副本。只要它继续写入，就把复制边界埋进了参数传递。

返回字符串后不要把 Builder 当作可分支缓存

String() 返回当前构建结果，适合在函数末尾直接返回：

func routeKey(region, code string) string {
    var b strings.Builder
    b.WriteString(region)
    b.WriteByte('/')
    b.WriteString(code)
    return b.String()
}

如果业务需要两个不同结果，应分别声明两个 Builder，而不是先写一份、复制一份再追加后缀：

func labels(prefix string) (string, string) {
    var left strings.Builder
    left.WriteString(prefix)
    left.WriteString("-left")

    var right strings.Builder
    right.WriteString(prefix)
    right.WriteString("-right")
    return left.String(), right.String()
}

这会多写几行，但把所有权说清楚了：每个 Builder 只有一个写入者，没有“复制后再分叉”的隐藏状态。

接口、结构体和并发场景里的复制陷阱

最容易漏查的是结构体和接口。把 Builder 放进结构体后，结构体赋值、按值返回、按值传参都可能连带复制它：

type responseText struct {
    body strings.Builder
}

func clone(r responseText) responseText {
    return r // 连同 body 一起发生值复制
}

如果结构体只是承载最终字符串，更适合在构建完成后保存 string；如果它必须继续写入，就让相关函数接收 *responseText，并避免返回结构体副本。接口同理：不要为了统一参数把 Builder 值装进 any，那会掩盖真正的所有权。

另外，Builder 不是并发安全的缓冲区。多个 goroutine 同时调用同一个 Builder 的写方法，既可能产生数据竞争，也可能让问题表现得像复制错误。并发场景应当让每个 goroutine 使用自己的 Builder，最后再按明确顺序合并字符串。

常见问题

strings.Builder 需要调用 New 才能使用吗？

不需要。零值 Builder 可以直接调用写入方法；只有在明确知道容量时，才考虑 Grow 做容量预留。

复制 Builder 后只读取 String 可以吗？

不要把复制后的值当成稳定快照。即使暂时只读取，也会把复制边界藏在代码里；需要快照时直接保存 b.String() 的结果。

怎样定位 illegal use of non-zero Builder copied by value？

搜索 Builder 的赋值、结构体值传递、按值返回和接口装箱，再检查报错前是否发生了写入。重点看“谁复制了 Builder”，而不是只看最后一次写操作。

小结

strings.Builder 的高效来自内部状态管理，也因此不适合复制。局部零值直接写、跨函数用指针、结果用字符串传递；要构造多个分支，就为每个结果创建独立 Builder。把这几条边界固定下来，illegal use of non-zero Builder copied by value 通常就能在代码审查阶段被发现。