Go io.CopyN 复制指定字节时为什么会返回 ErrUnexpectedEOF

用 io.CopyN 复制固定长度数据时，看到 ErrUnexpectedEOF，先不要把它理解成“CopyN 自己把普通 EOF 改名了”。对于源数据自然结束且实际字节数少于 n 的情况，标准库的 CopyN 通常返回 io.EOF；只有底层 Reader 已经返回 io.ErrUnexpectedEOF，这个更具体的错误才会沿着复制链路传到调用方。真正的判断条件始终是：written == n 才算固定长度复制完成。

先区分 io.CopyN 的成功条件和短源输入

io.CopyN(dst, src, n) 的语义是“最多从 src 复制 n 个字节”。返回值中的 written 记录真实写入 dst 的字节数，只有 written == n 且 err == nil，调用方才能把目标块当成完整数据。

package main

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

func main() {
    src := strings.NewReader("abc")
    var dst strings.Builder

    // 请求 5 字节，但源只有 3 字节，用返回值识别短源输入。
    written, err := io.CopyN(&dst, src, 5)
    fmt.Printf("written=%d data=%q err=%v isEOF=%t\n", written, dst.String(), err, err == io.EOF)
}

这个场景的关键结果是 written=3、数据为 abc，错误通常是 io.EOF。它表示源流正常结束，但没有满足调用方要求的 5 字节，不等于目标块可以继续按完整格式解析。

为什么底层 Reader 会把 ErrUnexpectedEOF 传上来

Go 官方实现先把源包装成 io.LimitReader(src, n)，再调用复制逻辑；如果写够 n 字节就返回成功，如果少于 n 且复制过程没有错误，才补成普通 io.EOF。因此，ErrUnexpectedEOF 不是短读的统一别名，而是某个更底层的 Reader 已明确报告了“固定结构读到中途结束”。

type truncatedReader struct{}

func (truncatedReader) Read(p []byte) (int, error) {
    // 只交付一部分数据，同时明确声明结构化内容已经截断。
    copy(p, []byte("abc"))
    return 3, io.ErrUnexpectedEOF
}

func copyBlock() (int64, error) {
    var dst strings.Builder
    // CopyN 保留底层的具体错误，调用方可以据此拒绝半包。
    return io.CopyN(&dst, truncatedReader{}, 5)
}

这里的返回值会带着 io.ErrUnexpectedEOF。常见来源包括定长协议解码器、压缩或编码层，以及自行实现并遵守“部分数据加具体错误”约定的 Reader。CopyN 负责复制边界，不负责替底层判断数据格式。

按返回字节数与错误值处理截断

调用方不要只写“有错误就返回”或只比较错误字符串。先把 written 当作已交付字节数，再决定这些字节是否有业务意义。对于文件块、消息帧或协议头，未达到长度就应该停止解析，避免半包被当成合法对象。

func copyFixed(dst io.Writer, src io.Reader, size int64) error {
    written, err := io.CopyN(dst, src, size)
    if written != size {
        // 半包不能当作完整记录；保留底层错误供上层判断。
        if err == nil {
            return fmt.Errorf("short copy: wrote %d of %d bytes", written, size)
        }
        return fmt.Errorf("fixed block truncated after %d bytes: %w", written, err)
    }
    return err
}

生产代码里可以使用 errors.Is(err, io.ErrUnexpectedEOF) 判断包装后的错误。不要用 err.Error() == "unexpected EOF"，因为上层通常会补充文件名、块号或请求标识。

需要完整固定长度时如何选择 ReadFull

如果目标就是把一个缓冲区填满，io.ReadFull 表达得比 CopyN 更直接。它会持续读取，直到填满 buf 或遇到错误；读到部分数据后遇到 EOF 时返回 io.ErrUnexpectedEOF，调用方可据此把它视为不完整记录。

func readHeader(r io.Reader) ([]byte, error) {
    header := make([]byte, 8)
    // ReadFull 的成功条件是 n 等于缓冲区长度。
    n, err := io.ReadFull(r, header)
    if err != nil {
        return nil, fmt.Errorf("read header %d/8 bytes: %w", n, err)
    }
    return header, nil
}

可以这样选择：目标是“把 Reader 的一段内容搬到 Writer”，使用 CopyN；目标是“填满一个定长字节切片”，使用 ReadFull；目标是“最多读取 n 字节，读到自然 EOF 也算正常”，使用 LimitReader 配合 Copy 或 ReadAll。API 的选择应跟数据协议的成功定义一致。

把错误分类写进调用方的兼容策略

网络流中，短读可能意味着连接提前关闭，也可能是协议层已经确认消息损坏；文件读取中，则常常需要记录路径、块偏移和实际字节数。重试前先确认源是否可重放：普通网络请求可重新建立连接，已经消费过且不可 Seek 的流则不能盲目从当前位置重试。

一个稳妥的原则是：完整块才进入下一层；io.EOF 表示源不足，io.ErrUnexpectedEOF 表示底层已报告结构化截断，其他错误保留原始上下文。这样既不会把正常结束误报成系统故障，也不会把损坏的半包悄悄写入后续流程。

常见问题

io.CopyN 少复制一些字节时一定返回 ErrUnexpectedEOF 吗？

不一定。源自然结束且 CopyN 自己发现少于 n 时，标准路径通常返回 io.EOF；只有底层 Reader 提前返回 io.ErrUnexpectedEOF 等具体错误时，CopyN 才会保留它。

为什么 written 大于 0 仍然不能使用结果？

因为 fixed-size 数据的完整性由目标长度决定。written > 0 只说明部分字节已经写出，不能证明头部、帧或记录完整。

可以把 EOF 和 ErrUnexpectedEOF 都忽略吗？

只有业务明确允许截断并且不会继续按完整格式解析时才可以。协议、压缩包或定长文件块通常应保留错误并丢弃半包。