Go io.Copy 报 short write 是读端还是写端出错

如果 io.Copy 返回 short write，先查目标 io.Writer，不是先怀疑读端。Go 对 io.ErrShortWrite 的定义是：写入方接收的字节数少于请求数量，却没有返回明确错误。也就是说，复制过程中通常已经从 Reader 读到了数据，真正不符合契约的是 Writer 的 Write 返回值。

判断顺序可以很简单：先看 written 和 err，再检查 Writer 是否出现 n 且 err == nil。只有当错误是自定义读取错误或网络读取错误时，才把排查重点放到 Reader。

先看 written 和 error 的组合

io.Copy 返回两个关键值：已写入的字节数和复制中遇到的第一个错误。正常读到 EOF 不算失败，成功时 err 是 nil；如果目标 Writer 只写了一部分却返回空错误，复制逻辑才会把它归一成 io.ErrShortWrite。

核对 Writer 的 Write 契约

io.Writer 要求：Write(p) 返回的 n 必须在 0 到 len(p) 之间；只要 n ，就必须同时返回非空错误。下面这个 Writer 故意违反了约定，所以 io.Copy 会得到 short write：

package main

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

// brokenWriter 模拟只接收一部分数据却返回 nil 的错误实现。
type brokenWriter struct{}

func (brokenWriter) Write(p []byte) (int, error) {
    if len(p) == 0 {
        return 0, nil
    }
    return 1, nil // 少写但不报错，违反 io.Writer 契约
}

func main() {
    written, err := io.Copy(brokenWriter{}, strings.NewReader("abcdef"))
    fmt.Println(written, err)
    fmt.Println(errors.Is(err, io.ErrShortWrite)) // true
}

这里的根因在 brokenWriter.Write，不是 strings.Reader。真实项目中常见的类似问题包括自定义压缩 Writer、限流 Writer、分片上传适配器，以及把底层网络返回值错误转换的包装层。修复方式不是忽略 io.ErrShortWrite，而是让 Writer 在少写时返回具体错误，或者在内部正确处理剩余切片。

用 Reader 错误做对照

如果 Reader 自己返回一个错误，io.Copy 通常会保留这个错误。Reader 允许一次读取返回 n > 0 和错误，调用方要先处理这批数据；因此看到 written 大于零，并不能直接说明是 Writer 出错。

type failReader struct {
    sent bool
}

func (r *failReader) Read(p []byte) (int, error) {
    if r.sent {
        return 0, errors.New("source stream interrupted") // 模拟源端中断
    }
    copy(p, "hello")
    r.sent = true
    return 5, nil
}

func copyFromSource() error {
    var dst bytes.Buffer
    written, err := io.Copy(&dst, &failReader{})
    if err != nil {
        return fmt.Errorf("copy %d bytes from source: %w", written, err) // 保留原始错误
    }
    return nil
}

排查时可以用 errors.Is 或 errors.As 判断错误链，不要只比较字符串。若错误是连接关闭、超时或业务 Reader 返回的自定义错误，应沿着 Reader 的包装层继续查；若错误能匹配 io.ErrShortWrite，优先回到 Writer 的写入契约。

别忘了 io.Copy 可能绕过缓冲区

io.Copy 并不保证每次都使用内部缓冲循环。官方实现会优先检查源端是否实现 io.WriterTo，否则再检查目标端是否实现 io.ReaderFrom；只有两者都没有时，才使用普通的缓冲复制路径。即使调用 io.CopyBuffer，这两个能力存在时提供的 buffer 也可能不参与复制。

因此建议按下面的清单定位：

• 先打印 written，并用 errors.Is(err, io.ErrShortWrite) 判断是否为标准短写。
• 检查目标对象的具体类型，确认它是否自定义了 Write、ReadFrom，以及包装器是否改变了返回值。
• 检查源对象是否实现 WriteTo；它可能绕过你以为会经过的 Writer 包装层。
• 对文件、HTTP 响应体、io.Pipe 和网络连接分别记录关闭时机，区分显式错误与半关闭。
• 如果已经写出部分内容，按业务决定删除半成品、截断重试，还是从 written 位置续传。

常见问题

short write 一定是网络断开吗？

不一定。它首先表示 Writer 少写且没有提供错误，可能是自定义适配器的实现缺陷；网络断开通常会带有连接错误、超时或关闭管道等更具体的错误。

把 io.ErrShortWrite 重试就能解决吗？

不能直接重试。先修复 Writer 的返回契约，并根据 written 判断目标是否已经产生部分结果，否则重试可能重复写入。

io.CopyBuffer 能强制暴露读写问题吗？

不能保证。源端的 WriterTo 或目标端的 ReaderFrom 存在时，提供的 buffer 可能不会被使用，仍要检查这些接口的实现。

把 short write 当作“写端没有按约定报告少写”来处理，通常比盯着错误字符串更快。保留 written、错误链和实际接口类型，才能判断该修 Writer、查 Reader，还是处理部分写入后的恢复策略。