Go io.Copy 复制大文件时的缓冲与截断处理

io.Copy 复制大文件时不会把整份内容一次读入内存。它会持续从源读取并写入目标，优先调用源的 WriterTo，其次调用目标的 ReaderFrom，只有两者都没有时才走通用缓冲循环。真正容易出错的地方不是“文件太大”，而是覆盖旧目标时没有截断，以及把正常 EOF 当成唯一的完整性判断。

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

io.Copy 不会把大文件一次读入内存

Go 官方文档规定，io.Copy 会复制到源返回 EOF 或发生错误为止；成功时返回的错误是 nil，而不是 io.EOF。它还会先检查 WriterTo 和 ReaderFrom 两个接口，因此文件、网络连接或自定义 Reader/Writer 可能走自己的优化实现。

标准库通用分支在没有提供缓冲时分配 32 KiB 空间，所以复制 100 GB 文件并不等于占用 100 GB 内存。最小写法只需要正确打开和关闭两端：

func copyDirect(srcPath, dstPath string) (int64, error) {
    src, err := os.Open(srcPath)
    if err != nil {
        return 0, fmt.Errorf("打开源文件: %w", err)
    }
    defer src.Close() // 函数返回时释放源文件描述符。

    dst, err := os.OpenFile(
        dstPath,
        os.O_WRONLY|os.O_CREATE|os.O_TRUNC, // 覆盖旧目标时立即截断为 0。
        0o644,
    )
    if err != nil {
        return 0, fmt.Errorf("打开目标文件: %w", err)
    }

    n, copyErr := io.Copy(dst, src) // 流式复制，返回实际写入字节数。
    closeErr := dst.Close()         // Close 的延迟写入错误也不能忽略。
    if copyErr != nil {
        return n, fmt.Errorf("复制内容: %w", copyErr)
    }
    if closeErr != nil {
        return n, fmt.Errorf("关闭目标文件: %w", closeErr)
    }
    return n, nil
}

这段代码适合“失败后允许目标成为不完整文件”的场景，例如一次性导出目录或可重新生成的缓存。因为 O_TRUNC 在打开时就清空旧目标，只要后续复制失败，原内容已经无法恢复。

覆盖旧目标时必须明确截断

假设目标原来有 10 MB，新的源只有 6 MB。如果目标用 O_WRONLY|O_CREATE 打开，写入位置从开头开始，但文件长度不会自动缩短，最终可能是“前 6 MB 新内容 + 后 4 MB 旧内容”。O_TRUNC 的含义正是打开可写普通文件时把长度截断为 0。

如果目标内容不能在失败时被破坏，就不要直接截断最终路径。更稳妥的边界是把 O_TRUNC 用在新建的临时文件上，只有复制、同步和关闭都成功后才替换最终名称。

已知长度时用 CopyN 识别提前 EOF

io.Copy 把 EOF 当成正常结束，所以源文件在复制期间被另一个进程截短时，复制可能得到更少字节但错误仍为 nil。如果开始前已经读取普通文件长度，可以用 io.CopyN 要求复制恰好这么多字节。官方契约是：返回字节数等于要求值，当且仅当错误为 nil；源提前结束会返回 io.EOF。

info, err := src.Stat()
if err != nil {
    return fmt.Errorf("读取源文件信息: %w", err)
}
if !info.Mode().IsRegular() {
    // 管道和设备没有稳定的普通文件长度，不适合这个 CopyN 方案。
    return fmt.Errorf("源不是普通文件: %s", srcPath)
}

expected := info.Size()
n, err := io.CopyN(dst, src, expected) // 要求复制开始时记录的完整长度。
if err != nil {
    return fmt.Errorf("源文件提前结束，已复制 %d/%d 字节: %w", n, expected, err)
}
if n != expected {
    // 按 CopyN 契约通常不会进入这里，保留检查便于维护和日志定位。
    return fmt.Errorf("字节数不一致: got=%d want=%d", n, expected)
}

这仍然不是文件快照：另一个进程可以在复制时改写同样长度的内容，也可以在原长度之后追加数据。需要一致快照时，应由生产者加锁、先生成不可变版本，或使用文件系统/存储系统提供的快照能力。

临时文件、Sync 与 Rename 组成替换边界

下面的小项目把复制目标改成同目录临时文件。这样复制错误、磁盘写满或关闭失败时只删除临时文件，原目标不动。选择同目录还能避免常见的跨文件系统重命名失败。

func copyFileSafely(srcPath, dstPath string) (written int64, err error) {
    src, err := os.Open(srcPath)
    if err != nil {
        return 0, fmt.Errorf("打开源文件: %w", err)
    }
    defer src.Close() // 源只读，统一在函数结束时关闭。

    info, err := src.Stat()
    if err != nil {
        return 0, fmt.Errorf("读取源文件信息: %w", err)
    }
    if !info.Mode().IsRegular() {
        return 0, fmt.Errorf("只支持普通文件: %s", srcPath)
    }

    dir := filepath.Dir(dstPath)
    base := filepath.Base(dstPath)
    tmp, err := os.CreateTemp(dir, "."+base+".part-*")
    if err != nil {
        return 0, fmt.Errorf("创建临时文件: %w", err)
    }
    tmpName := tmp.Name()
    committed := false
    defer func() {
        if tmp != nil {
            _ = tmp.Close() // 主路径会检查 Close；这里只负责兜底释放。
        }
        if !committed {
            _ = os.Remove(tmpName) // 失败时只清理临时文件，保留旧目标。
        }
    }()

    if err := tmp.Chmod(info.Mode().Perm()); err != nil {
        return 0, fmt.Errorf("设置目标权限: %w", err)
    }

    written, err = io.CopyN(tmp, src, info.Size())
    if err != nil {
        return written, fmt.Errorf("复制内容: %w", err)
    }
    if err := tmp.Sync(); err != nil {
        return written, fmt.Errorf("同步临时文件: %w", err)
    }
    if err := tmp.Close(); err != nil {
        return written, fmt.Errorf("关闭临时文件: %w", err)
    }
    tmp = nil // 避免 defer 再次关闭已经成功关闭的句柄。

    if err := os.Rename(tmpName, dstPath); err != nil {
        return written, fmt.Errorf("替换目标文件: %w", err)
    }
    committed = true
    return written, nil
}

File.Sync 把文件当前内容提交到稳定存储，但“重命名是否原子地覆盖已有目标”以及崩溃后的目录项持久性仍受操作系统和文件系统影响。Go 的 os.Rename 文档明确提醒：即便同目录，在非 Unix 平台也不保证原子。跨平台程序应在目标系统测试覆盖语义，必要时采用平台专用替换 API。

缓冲大小与元数据边界

io.CopyBuffer 适合复用调用方管理的缓冲，例如批处理许多不实现优化接口的 Reader。它并不是“复制大文件必须调用”的版本。若源实现 WriterTo 或目标实现 ReaderFrom，传入的缓冲不会参与复制；零长度缓冲还会触发 panic。

buf := make([]byte, 256*1024) // 复用缓冲，减少批量任务中的临时分配。

for _, job := range jobs {
    // 每轮开始前由调用方正确打开并截断目标文件。
    n, err := io.CopyBuffer(job.Dst, job.Src, buf)
    if err != nil {
        return fmt.Errorf("复制 %s，已写入 %d 字节: %w", job.Name, n, err)
    }
}

缓冲越大不一定越快，最佳值取决于存储、文件系统和并发量。先用 io.Copy，只有基准测试显示通用缓冲路径是瓶颈时再调整。还要注意，内容复制不会自动保留修改时间、所有权、扩展属性、访问控制列表或稀疏文件洞；示例只复制权限位。需要完整文件语义时，应把这些元数据列成独立需求。

验收清单

• 用“新源比旧目标短”的样例确认目标没有旧尾部。
• 模拟目标写入失败，确认旧目标未被临时文件方案破坏。
• 记录 io.Copy 或 io.CopyN 返回的字节数，不只检查错误。
• 确认源是否可能在复制期间变化；需要一致性时先冻结或快照。
• 按目标平台验证 os.Rename 覆盖已有文件的行为。

常见问题

io.Copy 的默认缓冲一定是 32 KiB 吗？

只有通用分支通常会分配 32 KiB 缓冲。源实现 WriterTo 或目标实现 ReaderFrom 时，io.Copy 会优先调用接口实现，复制策略和缓冲由具体类型决定。

为什么 io.Copy 返回 nil 仍可能少于预期长度？

因为 EOF 对 io.Copy 是正常结束。如果业务知道预期长度，就比较返回字节数，或用 io.CopyN 让提前 EOF 成为错误。

os.Create 会不会截断旧文件？

会。os.Create 的语义是创建或截断目标。它适合简单覆盖，但复制失败会留下不完整的新文件；重要目标应先写临时文件。

CopyBuffer 能保证更高速度吗？

不能。它主要让调用方提供并复用缓冲，而且在 WriterTo/ReaderFrom 分支中缓冲会被忽略。应通过基准测试决定是否需要它。