Go base64.Decode 返回 n 和错误时怎么处理已写入字节

Go 的 base64.Encoding.Decode 返回的 n 和 err 必须成对处理：n 表示已经成功写入目标缓冲区的字节数，输入包含非法 Base64 字符时，err 通常是 base64.CorruptInputError。只要有错误，就不要把这段部分结果当成完整业务数据；如果只是排查问题，可以用 n 截取前缀并记录诊断信息。

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

最稳妥的判断顺序是：先保证目标缓冲区足够大，再检查 err；只有 err == nil 时，才把 dst[:n] 交给后续业务。

为什么 n 和 err 必须一起看

Decode 的签名是 Decode(dst, src []byte) (n int, err error)。它不会把结果直接返回成新切片，而是把解码字节写入调用者提供的 dst，然后返回实际写入数量。输入在中途出现非法字符时，前面的完整 Base64 分组可能已经写入，所以 n 可能大于零，同时 err 非空。

这也是它和“成功或失败二选一”的直觉不同之处。n 是写入进度，不是“这批数据可以安全使用”的承诺；err 是完整性边界。比如令牌、签名材料、序列化消息或文件内容，只要解码没有完成，就应该把整个结果视为不可交付，而不是拿前缀继续解析。

先准备目标缓冲区，再按 n 截断

目标缓冲区至少要能容纳 DecodedLen(len(src)) 个字节。这个长度是最大解码长度，实际成功长度可能更短，因此成功后要用 n 截断切片，避免把预分配但尚未写入的尾部零值传给调用方。

package main

import (
	"encoding/base64"
	"fmt"
)

func decodeComplete(src []byte) ([]byte, error) {
	// DecodedLen 给出目标缓冲区的最大容量，先分配再写入。
	dst := make([]byte, base64.StdEncoding.DecodedLen(len(src)))
	n, err := base64.StdEncoding.Decode(dst, src)
	if err != nil {
		// 出错时 n 只代表已经写入的前缀，不能当成完整消息返回。
		return nil, err
	}
	// 成功后按实际写入数量截断，去掉预分配的尾部空间。
	return dst[:n], nil
}

func main() {
	data, err := decodeComplete([]byte("SGVsbG8="))
	if err != nil {
		fmt.Println("decode error:", err)
		return
	}
	fmt.Printf("%q\n", data)
}

这里不能直接使用 dst，因为它的长度是最大容量。成功路径的边界是 dst[:n]；错误路径则应先返回错误，除非当前代码明确只把前缀用于诊断。

用 CorruptInputError 定位坏输入

官方文档将非法 Base64 输入对应为 base64.CorruptInputError，它本质上携带输入位置。不要通过匹配 err.Error() 的英文文本来判断错误类型；字符串适合日志，不适合业务分支。

package main

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

func inspectInput(src []byte) {
	dst := make([]byte, base64.StdEncoding.DecodedLen(len(src)))
	n, err := base64.StdEncoding.Decode(dst, src)
	if err == nil {
		// 没有错误时，n 才能定义完整有效结果的长度。
		fmt.Printf("complete=%q\n", dst[:n])
		return
	}

	var corrupt base64.CorruptInputError
	if errors.As(err, &corrupt) {
		// n 仅用于定位已解码前缀，不能绕过完整性检查。
		fmt.Printf("invalid base64 at input byte %d, prefix bytes=%d\n", int64(corrupt), n)
		return
	}
	// 保留未知错误的原始值，避免把异常误归类为输入损坏。
	fmt.Println("decode error:", err)
}

如果只是展示“坏字符前已经读到了什么”，可以在确认不进入业务链路后使用 dst[:n]。如果输出会被再次解析、写入数据库、参与签名或作为权限判断输入，就直接丢弃整次解码结果。

生产代码如何决定是否丢弃部分结果

可以把处理策略按数据用途分成三类：

• 协议数据、令牌和签名材料：只接受 err == nil 的完整结果；错误时记录位置并返回上层。
• 可恢复的文件或消息流：保留错误位置，交给重试或重新拉取流程，不在当前缓冲区上继续解析。
• 调试和诊断工具：可以显示 n 对应的前缀，但界面和日志要明确标记为部分结果。

还要注意换行：encoding/base64 会忽略输入中的回车和换行，因此不要把“出现换行”误判为损坏。真正需要关注的是解码错误本身，以及它对应的输入位置。

最后再回答几个容易混淆的问题：

• 为什么不直接用 DecodeString？它同样会返回部分解码数据和错误；需要复用目标缓冲区或控制写入位置时，Decode 更合适。
• n 为零能不能忽略错误？不能。零只说明没有成功写入字节，不代表输入格式或业务数据有效。
• 错误字符串能不能拿来展示？可以放进日志，但程序分支应优先使用错误类型或 errors.As。