Go 编码Base64 RawStdEncoding 解码填充错误怎么办

遇到 illegal base64 data at input byte ... 时，先不要把字符串机械地补上 =。这类错误最常见的根因，是发送方使用了无填充 Base64，而接收方却调用了要求标准填充的 StdEncoding；也可能反过来，输入带有 =，却拿 RawStdEncoding 去解码。

Go 里的 RawStdEncoding 等价于“标准字母表 + NoPadding”，它不是一个更宽松的解码器。修复的关键是先确认协议约定，再让编码器和输入形态匹配。

先看输入到底采用哪种 Base64 约定

Base64 的标准字母表使用 A-Z、a-z、0-9、+ 和 /。标准形式会用 = 把输出补齐到 4 个字符的边界；Raw 形式则省略这个填充。两者的字母表相同，但尾部约定不同。

因此，排查时先把“输入长什么样”和“代码选择了什么 Encoding”放在一起看：

下面这段是最小的选择示例。示例只表达调用关系和错误处理边界，不把任何输出当作线上运行证据。

package main

import (
	"encoding/base64"
	"fmt"
)

func decodeByContract(input string, raw bool) ([]byte, error) {
	// raw 必须来自协议约定，不要根据一次报错临时切换编码器。
	enc := base64.StdEncoding
	if raw {
		// RawStdEncoding 明确表示不使用末尾的 '=' 填充。
		enc = base64.RawStdEncoding
	}
	data, err := enc.DecodeString(input)
	if err != nil {
		// 返回原始错误，让调用方区分输入问题和业务处理问题。
		return nil, fmt.Errorf("decode base64: %w", err)
	}
	return data, nil
}

从错误类型判断是填充不匹配还是字符非法

DecodeString 遇到格式错误时会返回已经成功解出的部分数据和 base64.CorruptInputError。所以不要只记录“解码失败”，应把输入协议、编码器和错误位置一起记下来。

package main

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

func explainDecode(input string, enc *base64.Encoding) {
	// 使用指定 Encoding，避免排障代码偷偷改变协议语义。
	data, err := enc.DecodeString(input)
	if err == nil {
		fmt.Printf("decoded %q\\n", data)
		return
	}

	var corrupt base64.CorruptInputError
	if errors.As(err, &corrupt) {
		// CorruptInputError 携带输入中的错误位置，适合记录到排障日志。
		fmt.Printf("invalid base64 at byte %d\\n", int64(corrupt))
		return
	}
	// 其他错误仍要保留，不能把所有失败都归因于填充符。
	fmt.Printf("decode failed: %v\\n", err)
}

如果标准输入末尾有 =，优先尝试 StdEncoding；如果协议明确规定省略填充，优先使用 RawStdEncoding。错误位置落在字符集之外时，问题就不再是填充，而是混用了 URL-safe 字符、传输转义或不可见字符。

不要用补等号掩盖协议不一致

“缺几个等号就补几个”只适用于你已经确认上游采用标准 Base64、但传输层错误裁掉了填充的场景。若上游协议本来就是 Raw Base64，补回 = 只是改变了数据表示；更稳妥的做法是让双方统一字段约定，或者在协议适配层明确选择对应的 Encoding。

同样，不要无条件调用 strings.TrimRight(input, "=")。这样会把标准格式改成 Raw 格式，却没有同步改变解码器；对于签名、缓存键或需要保留原始表示的字段，还可能造成不可预期的比较差异。

package main

import (
	"encoding/base64"
	"fmt"
)

func decodeToken(token string, raw bool) ([]byte, error) {
	// 令牌格式由接口协议决定，调用方应在配置或版本契约中固定 raw。
	if raw {
		data, err := base64.RawStdEncoding.DecodeString(token)
		if err != nil {
			return nil, fmt.Errorf("decode raw token: %w", err)
		}
		return data, nil
	}
	data, err := base64.StdEncoding.DecodeString(token)
	if err != nil {
		return nil, fmt.Errorf("decode padded token: %w", err)
	}
	return data, nil
}

用边界测试确认修复没有改变约定

修复后至少覆盖同一组原始字节的带填充和无填充表示，并把错误输入分成三类：错误填充、非法字符、长度不符合当前约定。测试的目标不是让所有输入都能解码，而是让不符合协议的输入尽早失败。

package base64demo

import (
	"encoding/base64"
	"testing"
)

func TestDecodeContract(t *testing.T) {
	// 同一份数据对应两种合法表示，测试分别绑定各自的 Encoding。
	const padded = "SGVsbG8="
	const raw = "SGVsbG8"

	if got, err := base64.StdEncoding.DecodeString(padded); err != nil || string(got) != "Hello" {
		t.Fatalf("padded decode = %q, %v", got, err)
	}
	if got, err := base64.RawStdEncoding.DecodeString(raw); err != nil || string(got) != "Hello" {
		t.Fatalf("raw decode = %q, %v", got, err)
	}

	// 带填充输入交给 RawStdEncoding，应保留失败行为，防止协议被悄悄放宽。
	if _, err := base64.RawStdEncoding.DecodeString(padded); err == nil {
		t.Fatal("raw decoder unexpectedly accepted padded input")
	}
}

排查可以按下面的速查顺序收尾：

1. 记录输入是否含 =，以及是否来自 URL 或文件名字段。
2. 核对发送方的编码器和接收方的解码器是否成对。
3. 用 CorruptInputError 记录错误字节位置。
4. 只在协议明确允许时做格式转换，并为转换后的表示选择对应 Encoding。

相关问题

RawStdEncoding 和 RawURLEncoding 有什么区别？

两者都不使用 = 填充，但字母表不同。RawStdEncoding 保留标准 Base64 的 +、/；RawURLEncoding 使用适合 URL 和文件名的 -、_。

为什么 DecodeString 还能返回部分数据？

文档允许在发现格式错误前返回已经成功解出的字节，因此调用方只应在 err == nil 时把结果当作完整有效数据。

能否统一给所有输入补等号？

不建议。先确认发送方约定；补等号属于协议适配，不是通用修复，而且可能把 URL-safe、签名或原始表示转换成另一种语义。

一句话总结：RawStdEncoding 解决的是“标准字母表但无填充”的协议，不是“任何缺等号的字符串”。先对齐填充约定，再根据错误位置判断字符集和输入是否也匹配，解码错误才会真正消失。