Copy、CopyBuffer 与手写循环的差别主要在哪里

io.Copy、io.CopyBuffer 和手写 Read/Write 循环的主要差别，并不只是“缓冲区是不是自己传”。真正影响行为和性能的是三件事：是否命中 WriterTo/ReaderFrom 快路径、缓冲区由谁分配和复用、复制过程中是否需要增加进度、限速、校验或内容变换等新语义。

官方文档：https://pkg.go.dev/io

默认结论可以先记住：只想把 Reader 复制到 Writer，优先 io.Copy；明确需要跨多次复制复用缓冲区或实验缓冲大小，再用 io.CopyBuffer；只有标准库抽象无法表达额外行为时，才手写循环。

先看选型结论，不要先猜缓冲区大小

很多“CopyBuffer 一定更快”的结论都忽略了实际 Reader/Writer 类型。相同 API 在不同类型组合上可能走完全不同路径，所以基准必须记录源和目标的具体实现，不能只写“复制 10 MB 数据”。

io.Copy 不是简单的固定缓冲循环

io.Copy(dst, src) 首先检查源是否实现 io.WriterTo。如果实现，就调用 src.WriteTo(dst)；否则检查目标是否实现 io.ReaderFrom，存在时调用 dst.ReadFrom(src)。只有两个快路径都不存在时，才进入标准库的通用 Read/Write 循环。

这意味着某些文件、缓冲区、网络连接或包装器可以用更适合自己的实现复制数据，甚至减少中间分配或额外拷贝。手写一个看似直接的 32 KiB 循环，反而可能绕过这些能力。

图1：io.Copy 会先做接口分派，再决定是否进入通用缓冲循环。

普通场景的代码应保持简单：

package streamcopy

import (
    "fmt"
    "io"
)

func CopyAll(dst io.Writer, src io.Reader) (int64, error) {
    // 让标准库选择 WriterTo、ReaderFrom 或通用缓冲路径
    written, err := io.Copy(dst, src)
    if err != nil {
        return written, fmt.Errorf("copy stream after %d bytes: %w", written, err)
    }
    return written, nil
}

io.Copy 会一直复制到源返回 EOF 或出现其他错误。正常 EOF 被视为成功结束，因此成功时 err == nil。调用方不应期待返回 io.EOF 来表示成功。

CopyBuffer 的价值是控制与复用缓冲区

io.CopyBuffer 与 Copy 的复制语义相同，区别是当通用缓冲路径确实需要临时字节切片时，可以使用调用方提供的 []byte。传 nil 时仍会分配临时缓冲；传入长度为 0 的非 nil 切片会 panic。

最容易忽略的规则是：只要源实现 WriterTo 或目标实现 ReaderFrom，CopyBuffer 也会走快路径，调用方提供的 buf 不参与复制。于是“我传了 128 KiB 缓冲”不代表实际系统一定按 128 KiB 分块。

package streamcopy

import (
    "fmt"
    "io"
)

func CopyBatch(dst io.Writer, sources []io.Reader) (int64, error) {
    // 同一批任务复用 64 KiB 缓冲，减少通用路径上的重复分配
    buf := make([]byte, 64

这个写法的收益主要是所有复制都走通用缓冲路径时复用一个切片。如果 sources 中的类型实现 WriterTo，buf 可能一直没有被真正使用。是否减少分配，要看基准中的 allocs/op，不能仅凭代码表面判断。

手写循环真正增加的是语义负担

手写循环并不天然更快。它的合理理由通常是每块数据都要执行额外逻辑，例如更新哈希、汇报进度、限速、加密、内容过滤或分块落盘。与此同时，调用方必须完整实现 Reader 和 Writer 的边界规则。

一个最小但正确的通用循环至少要做到：

• Read 返回 n>0 时，先处理这 n 个字节，再判断 err。
• Write 返回的字节数小于请求长度且 err 为 nil 时，转成 io.ErrShortWrite。
• Writer 返回负数或大于输入长度的计数时，视为非法实现。
• 正常 io.EOF 不向上报错。
• 持续出现 0, nil 时防止无进展死循环。

package streamcopy

import (
    "errors"
    "fmt"
    "io"
)

var ErrNoProgress = errors.New("reader made no progress")

func CopyWithProgress(
    dst io.Writer,
    src io.Reader,
    buf []byte,
    report func(total int64),
) (int64, error) {
    if len(buf) == 0 {
        return 0, errors.New("copy buffer must not be empty")
    }

    var total int64
    emptyReads := 0

    for {
        nr, readErr := src.Read(buf)

        if nr > 0 {
            emptyReads = 0
            nw, writeErr := dst.Write(buf[:nr])
            if nw  nr {
                return total, fmt.Errorf("invalid write count: %d for %d", nw, nr)
            }

            total += int64(nw)
            if report != nil {
                // 只报告已经成功写入目标的字节数
                report(total)
            }

            if writeErr != nil {
                return total, fmt.Errorf("write after %d bytes: %w", total, writeErr)
            }
            if nw != nr {
                return total, io.ErrShortWrite
            }
        } else if readErr == nil {
            emptyReads++
            if emptyReads >= 100 {
                return total, ErrNoProgress
            }
        }

        if readErr != nil {
            if errors.Is(readErr, io.EOF) {
                // Read 可能同时返回 n>0 和 EOF，数据已在上方处理
                return total, nil
            }
            return total, fmt.Errorf("read after %d bytes: %w", total, readErr)
        }
    }
}

这个示例为了展示规则而写。标准库的 io.Copy 已经处理了通用复制的核心边界；如果只是想统计进度，通常可以先考虑用 io.TeeReader、计数 Reader/Writer 包装器或在目标 Writer 外加装饰器，而不是立即重写整个复制循环。

三种方案怎么选

图2：三种复制方案的选型边界。

可以按下面的判断顺序：

1. 只需要完整复制且接受标准错误语义：用 io.Copy。
2. 确认落入通用路径，并且大量重复复制导致缓冲分配可见：用 CopyBuffer 复用切片。
3. 需要比较不同缓冲大小：用 CopyBuffer，但先排除 WriterTo/ReaderFrom 快路径。
4. 每块都要加入业务行为：优先组合 Reader/Writer 包装器；组合表达不了再手写循环。

性能基准应先控制接口快路径

指标驱动的对比至少记录 ns/op、MB/s、B/op 和 allocs/op。更重要的是要分别测“真实类型组合”和“强制通用路径”两组，否则 Copy 可能走 WriterTo，而手写循环只能走 Read/Write，两者对比的其实是不同实现。

下面的基准使用一个只暴露 Reader 接口的包装器，避免 bytes.Reader 的额外接口影响通用路径；每轮重新构造源，目标使用 Discard，重点观察复制框架本身。

package streamcopy

import (
    "bytes"
    "io"
    "testing"
)

type readerOnly struct {
    r io.Reader
}

func (r readerOnly) Read(p []byte) (int, error) {
    // 只暴露 Read，避免基准意外命中 WriterTo
    return r.r.Read(p)
}

var benchData = bytes.Repeat([]byte("17golang-copy\n"), 64

# 同一台机器上重复运行，查看吞吐、分配与波动
go test -run '^$' -bench 'Copy' -benchmem -count=5

这个基准不能代替生产环境：文件系统页缓存、磁盘、TLS、内核发送路径、网络拥塞和目标存储都会改变结论。先用微基准判断分配与复制框架，再用真实源和目标做端到端测试。

为什么缓冲区更大不一定更快

通用路径中，较大缓冲可能减少 Read/Write 调用次数，但也增加每个并发复制任务的驻留内存，并可能降低 CPU 缓存友好性。复制 1000 个并发流时，每流多 256 KiB 就不再是小成本。

标准库通用路径通常分配 32 KiB 临时缓冲；当源是剩余量更小的 LimitedReader 时，还会相应缩小。这个默认值是通用折中，不是所有工作负载的最优点。只有基准显示调用次数或分配确实是瓶颈时，才值得测试 16、32、64、128 KiB 等候选值。

常见误区

CopyBuffer 一定零分配吗？不一定。你可以复用传入切片，但源、目标和包装器仍可能分配；快路径存在时 buf 甚至不会被使用。

手写循环能强制使用指定缓冲吗？可以，但代价是失去标准库接口分派，并承担全部错误语义。除非指定分块本身就是业务需求，否则不是优势。

Copy 能保证一次 Write 对应一次 Read 吗？不能。快路径可能完全改变调用方式，通用循环也不承诺固定边界。依赖分块边界的协议应使用明确的 framing，而不是观察 Copy 的内部调用。

出现 EOF 时 written 是否可信？可信。Copy 把正常 EOF 转为 nil，written 是成功写入的总字节数；其他错误发生时也会返回此前已复制的字节数。

最终边界

三种方案的层次可以概括为：io.Copy 选择最佳现有能力，io.CopyBuffer 控制通用路径的临时缓冲，手写循环创造标准库没有的新语义。它们不是从“慢”到“快”的三级阶梯，而是从“复用抽象”到“承担更多责任”的三级选择。

因此，遇到复制性能问题时先记录具体 Reader/Writer 类型和是否命中 WriterTo/ReaderFrom，再观察吞吐与分配；不要在没有基准的情况下把 Copy 换成手写循环。能让标准库正确完成的工作，就把复杂度留给标准库；只有需求本身超出 Copy 的语义时，才把复杂度带回业务代码。