Go io.CopyBuffer 传入零长度缓冲区为什么会 panic

这个 panic 通常不是读写端实现错了，而是把一个“非 nil、长度为 0”的切片当成了可复用缓冲区。io.CopyBuffer 的规则很明确：传入 nil 时由标准库分配内部缓冲区；传入 make([]byte, 0)、buf[:0] 这类零长度但非 nil 的切片时，会在复制开始前直接触发 panic: empty buffer in CopyBuffer。

先区分 nil 与零长度切片，panic 发生在入口

Go 切片的 len 与“是否为 nil”是两个独立属性。var a []byte 得到的是 nil 切片；make([]byte, 0) 的长度也是 0，但它不是 nil。对 io.CopyBuffer 来说，只有第二种组合会触发这个 panic。

package main

import (
    "bytes"
    "fmt"
    "io"
)

func main() {
    var nilBuf []byte           // nil 代表交给 io.CopyBuffer 默认分配
    emptyBuf := make([]byte, 0) // 非 nil 但长度为 0，会触发入口检查
    safeBuf := make([]byte, 32) // 长度大于 0，可作为复用缓冲区

    fmt.Println(nilBuf == nil, len(nilBuf))
    fmt.Println(emptyBuf == nil, len(emptyBuf))
    fmt.Println(safeBuf == nil, len(safeBuf))

    var dst bytes.Buffer
    _, _ = io.CopyBuffer(&dst, bytes.NewBufferString("ok"), safeBuf)
    fmt.Println(dst.String()) // 只有 safeBuf 进入复制路径
}

因此，问题重点不是“缓冲区容量够不够”，而是调用者把长度为 0 的切片传进了一个要求可写入空间的 API。下面这张结构说明图把三种状态放在同一个入口上比较。

CopyBuffer 的快路径不能绕过空缓冲区检查

源码入口先判断 buf != nil && len(buf) == 0，命中后立即 panic；只有通过这一步，才会进入内部复制函数。内部函数随后才会判断源是否实现 WriterTo，或目标是否实现 ReaderFrom。

这意味着，即使源或目标具备高效快路径，空缓冲区仍然会在更早的位置被拒绝。快路径的含义是“通过入口检查后可以不使用 buf”，不是“入口参数可以随便传”。

配置化缓冲区的安全修复方式

生产代码里，零长度参数常来自配置、环境变量换算、切片截取或对象复用。修复时不要只给 panic 加 recover，那会把调用契约错误推迟成更难排查的半失败状态。应在组装参数时决定“默认分配”还是“固定缓冲区”。

func copyWithConfiguredBuffer(dst io.Writer, src io.Reader, size int) (int64, error) {
    var buf []byte
    if size > 0 {
        buf = make([]byte, size) // 只有正数配置才创建可写缓冲区
    }
    // size 

如果业务确实要求复用一块已有内存，应检查 len(buf)，而不是只检查 cap(buf)。例如 buf[:0] 虽然可能拥有很大的容量，但传给 CopyBuffer 时长度仍为 0；要么传 buf[:cap(buf)]，要么重新按明确的正长度切片，前提是调用者确实拥有那段内存。

可以把排查收敛为四项：第一，打印或记录进入调用点的 buf == nil 与 len(buf)；第二，搜索是否存在 make([]byte, 0)、[:0] 或配置值转切片；第三，确认 panic 文本是否精确为 empty buffer in CopyBuffer；第四，再看 WriterTo/ReaderFrom 是否影响性能，而不要把它们当成修复手段。

相关问题

传 nil 会不会导致每次复制都重复分配？

不一定。它表示由 io 内部按当前调用分配所需缓冲区；如果调用频繁且分配成为热点，再考虑复用正长度缓冲区或使用池，但不要用零长度切片代替 nil。

把 buf[:0] 改成 buf[:cap(buf)] 一定安全吗？

只有确认容量对应的内存仍然有效、且这次调用允许使用整段空间时才可以。更稳妥的方案是由创建方直接保证正长度，或在配置异常时回退到 nil。

为什么 panic 不是 error 返回值？

零长度非 nil 缓冲区违反了 CopyBuffer 的参数契约，标准库在入口用 panic 明确暴露调用方错误；普通的读写失败仍会通过返回的 error 传回。