Go base64.NewDecoder 遇到截断输入为什么还能返回部分数据

先说结论：base64.NewDecoder 是一个流式 io.Reader。它会先把已经凑齐的 Base64 分组解码，所以底层输入提前结束时，之前完整分组对应的字节仍然可能通过 Read 返回；等到读取器确认末尾还有未完成的编码分组时，才会报告 io.ErrUnexpectedEOF。因此，判断成功不能只看 n > 0，也不能只看某一次读取没有错误。

官方文档：https://pkg.go.dev/encoding/base64#NewDecoder

这类场景最容易出现在文件上传、消息分片和管道读取中。正确的处理顺序是：先消费本次 n 个字节，再根据 err 判断输入是完整结束、意外截断，还是包含非法 Base64 字符。

先按四字符分组理解截断位置

标准 Base64 通常以 4 个编码字符为一个量子，完整量子最多还原 3 个字节。NewDecoder 不要求底层 Reader 一次交付完整分组，它会在内部缓存跨 Read 到达的字符；只要缓存中已经有完整分组，就可以先把对应的明文交给上层。

例如输入前半段包含两个完整分组，最后又收到两个字符就结束。前两个完整分组已经产生的明文是确定的，但最后两个字符不足以完成标准 Base64 量子。此时“已有数据”和“输入完整”是两个不同结论，不能因为前者成立就把整个消息标记为成功。

如果使用的是无填充编码，末尾合法的 2 或 3 个字符可以按无填充规则解出最后片段；本文讨论的 base64.StdEncoding 默认带填充，末尾缺少必要字符时应按截断处理，而不是自行补零后继续提交。

用 NewDecoder 观察 n 和 err 的先后关系

下面的示例故意把一个完整编码串截掉最后两个字符，再交给 NewDecoder。循环里先处理 n > 0，然后才处理错误；这样即便最后一次同时带回部分数据和错误，也不会因为先返回错误而丢掉数据。

package main

import (
    "bytes"
    "encoding/base64"
    "fmt"
    "io"
)

func main() {
    // 先得到完整编码，再截掉末尾字符，模拟传输在一个量子中途结束。
    full := base64.StdEncoding.EncodeToString([]byte("Hello, world!"))
    truncated := full[:len(full)-2]
    decoder := base64.NewDecoder(base64.StdEncoding, bytes.NewReader([]byte(truncated)))

    var decoded bytes.Buffer
    buf := make([]byte, 5)
    for {
        n, err := decoder.Read(buf)

        // n 表示本次已经得到的明文字节，必须先消费它。
        if n > 0 {
            decoded.Write(buf[:n])
            fmt.Printf("收到 %d 字节，累计 %d 字节\n", n, decoded.Len())
        }

        // EOF 是完整结束；UnexpectedEOF 表示末尾仍缺少编码字符。
        if err != nil {
            if err == io.EOF {
                fmt.Printf("完整结束：%q\n", decoded.String())
            } else {
                fmt.Printf("输入未完整：%v，已保留 %d 字节\n", err, decoded.Len())
            }
            break
        }
    }
}

这个循环的关键不在于一次读多少字节，而在于把 n 和 err 当成两个独立信号。buf 只有 5 字节，解码器仍可以在内部按 4 字符分组；上层不应假设每次 Read 都对应一个完整业务消息。

区分正常结束与 UnexpectedEOF

对于带填充的标准 Base64，底层 Reader 返回 EOF 时，如果解码器内部还留有不足一个完整量子的字符，结果不是“正常结束”，而是 io.ErrUnexpectedEOF。它说明输入流结束得太早，已经返回的字节只能视为前缀或部分结果。

可以用下面的状态表来决定上层动作：

实际实现中，不同 Reader 或不同 Go 版本的具体返回时机可能让数据和错误出现在相邻的两次读取里，所以不要把“某一次 err == nil”当成完整性证明。完整性要到明确收到 io.EOF 且没有截断错误时才能确认。

截断和非法字符是两条排查路径

io.ErrUnexpectedEOF 表示输入在结构上还没有结束，常见原因是文件或消息被截断；base64.CorruptInputError 则表示解码器在某个输入位置遇到不符合编码规则的字符、错误填充或尾部垃圾。两者都可能发生在已经返回部分数据之后，但修复方向不同。

package main

import (
    "bytes"
    "encoding/base64"
    "errors"
    "fmt"
    "io"
)

func readBase64(src string) ([]byte, error) {
    decoder := base64.NewDecoder(base64.StdEncoding, bytes.NewBufferString(src))
    var out bytes.Buffer
    buf := make([]byte, 8)

    for {
        n, err := decoder.Read(buf)

        // 无论后面是否有错误，本次已解码的字节都先写入结果缓冲。
        if n > 0 {
            _, _ = out.Write(buf[:n])
        }
        if err == nil {
            continue
        }
        if errors.Is(err, io.EOF) {
            // 只有正常 EOF 才能把累计结果当成完整 Base64 内容。
            return out.Bytes(), nil
        }
        if errors.Is(err, io.ErrUnexpectedEOF) {
            // 输入不完整，返回结果的同时保留错误供上层决定是否重试。
            return out.Bytes(), fmt.Errorf("base64 input truncated: %w", err)
        }
        var corrupt base64.CorruptInputError
        if errors.As(err, &corrupt) {
            // 非法字符属于格式错误，不应和可续传的截断混在一起。
            return out.Bytes(), fmt.Errorf("base64 input invalid: %w", err)
        }
        return out.Bytes(), err
    }
}

注意这里使用 errors.Is 和 errors.As，是为了兼容上层给错误增加上下文的写法。若只用字符串比较错误文本，后续包装错误后就可能无法进入正确分支。

把读取循环变成可复用的安全流程

上层接口通常不只需要“读到多少”，还需要决定是否落盘、是否入队或是否继续等待。建议把完整性判断集中在一个函数里：部分数据可以暂存，但只有正常 EOF 才能提交为完整对象。

func decodeComplete(src io.Reader) ([]byte, error) {
    decoder := base64.NewDecoder(base64.StdEncoding, src)
    var out bytes.Buffer
    buf := make([]byte, 32*1024)

    for {
        n, err := decoder.Read(buf)

        // 先累计数据，再处理错误，避免丢失最后一次 Read 的有效字节。
        if n > 0 {
            _, _ = out.Write(buf[:n])
        }
        if err == nil {
            continue
        }
        if errors.Is(err, io.EOF) {
            // 只有正常 EOF 才交付完整对象。
            return out.Bytes(), nil
        }

        // 截断、非法字符和底层读取错误都不交付半成品。
        return nil, fmt.Errorf("decode base64 stream: %w", err)
    }
}

如果底层 Reader 来自网络，调用方可以在收到截断错误后保存已读长度和原始分片位置，等待业务层重新拉取；如果输入来自不可重试的上传，则应记录错误并明确拒绝半成品。无论采取哪种策略，都不要把累计缓冲直接当成成功结果。

常见误区速查

最后记住这条判断顺序

使用 base64.NewDecoder 时，第一步永远是处理本次返回的 n 个字节；第二步判断 err 是否为空；第三步把正常 io.EOF、io.ErrUnexpectedEOF 和 base64.CorruptInputError 分流。部分数据代表“已经完成的前缀”，不代表“完整输入已经验收”。

如果文章中的规则只保留一句话，可以记成：先收数据，再判结束；只有正常 EOF 才能交付完整 Base64 结果。

相关问题

为什么 Base64 截断后不是立刻返回错误？因为前面的完整四字符分组仍然可以独立解码，解码器会先交付这些已经确定的字节。

收到 UnexpectedEOF 时已经返回的字节能不能使用？可以作为诊断、缓存或续传前缀，但不能未经完整性确认就当成最终业务对象。

非法 Base64 字符和截断应该重试同一逻辑吗？通常不应该。截断偏向输入未完成，非法字符偏向格式或数据源错误，两者需要不同的修复路径。