Go base64 解码遇到非法字符怎样定位位置

Go 用 encoding/base64 解码时，如果输入里混入了不属于当前字母表的字节，常见错误就是 illegal base64 data at input byte N。这里的 N 不是模糊的错误编号，而是可以继续排查的输入位置：通常按零基字节偏移理解。要稳定定位，先用 errors.As 取出 base64.CorruptInputError，再用它的数值索引原始字符串；如果还要保留已经解出的内容，则改用 Decode 同时读取 n 和 err。

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

排查这类错误的关键不是把错误字符串截成数字，而是把 CorruptInputError 转成字节偏移，再打印偏移附近的原始字节。普通 Base64、URL-safe Base64、错误填充和 Strict 模式必须分开判断，不能一律删除字符后重试。

先确认错误值到底指向哪里

base64.CorruptInputError 的底层类型是 int64，它的 Error 方法才把数值拼成了 input byte N。因此最可靠的做法是保留原始 error，用类型断言或 errors.As 取出偏移。这个偏移是字节位置，从 0 开始，不是从 1 开始的“第几个字符”。

例如输入 SGVsbG8@IQ== 中，@ 位于索引 8，标准编码会把它识别为非法字节。下面的辅助函数同时打印偏移、字节值和附近上下文，适合放在导入接口或消息消费的错误日志里。

package main

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

// explainDecodeError 把标准库错误还原成可搜索的原始输入位置。
func explainDecodeError(src string, err error) string {
	var corrupt base64.CorruptInputError
	if !errors.As(err, &corrupt) {
		// 非 CorruptInputError 不强行解释，避免掩盖其他错误。
		return fmt.Sprintf("base64 decode failed: %v", err)
	}

	pos := int64(corrupt)
	if pos = int64(len(src)) {
		// 填充不足等情况可能指向输入末端，不能直接索引字符串。
		return fmt.Sprintf("base64 decode failed at byte %d: %v", pos, err)
	}

	start := pos - 4
	if start  int64(len(src)) {
		end = int64(len(src))
	}
	return fmt.Sprintf("base64 decode failed at byte %d, byte=0x%02x, context=%q",
		pos, src[pos], src[start:end])
}

func main() {
	// @ 不是 StdEncoding 的 64 个字母之一。
	src := "SGVsbG8@IQ=="
	_, err := base64.StdEncoding.DecodeString(src)
	if err != nil {
		fmt.Println(explainDecodeError(src, err))
	}
}

需要特别注意两个边界。第一，标准库把 \r 和 \n 当作可忽略的换行，所以看到日志中的偏移时，要回到“原始输入字节”而不是把换行过滤后的展示文本直接拿来数。第二，输入包含多字节 UTF-8 字符时，CorruptInputError 仍然按字节计数；如果业务日志按 Unicode 字符编号，需要在展示层再做一次转换。

用 Decode 把“已经成功的部分”与“失败位置”分开

DecodeString 适合一次性得到结果；当你需要记录已经处理了多少内容，或者要对流式导入给出更精确的诊断，可以直接调用 Decode。它返回写入目标缓冲区的字节数 n 和错误 err。发生损坏时，dst[:n] 才是已经写入的部分，dst[n:] 不能当成有效输出。

package main

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

func main() {
	// 目标缓冲区按最大解码长度分配，实际有效范围由 n 决定。
	src := []byte("SGVsbG8@IQ==")
	dst := make([]byte, base64.StdEncoding.DecodedLen(len(src)))
	n, err := base64.StdEncoding.Decode(dst, src)

	var corrupt base64.CorruptInputError
	if errors.As(err, &corrupt) {
		// n 是已写入字节数，corrupt 是原始输入的零基字节偏移。
		fmt.Printf("decoded=%q, written=%d, bad-byte=%d\n",
			dst[:n], n, int64(corrupt))
		return
	}
	if err != nil {
		// 其他错误按原样交给上层，不混入非法字符提示。
		fmt.Println("decode failed:", err)
		return
	}

	// 没有错误时同样只使用实际写入的 n 个字节。
	fmt.Printf("decoded=%q\n", dst[:n])
}

这段代码的排查价值在于同时保留了两条证据：n 告诉你解码器已经写入多少结果，corrupt 告诉你从哪一个输入字节开始失效。它们不是同一个坐标系，不能用解码后的字节数去反推坏字符位置。

按三类现象排查，而不是盲目清洗输入

定位到偏移后，下一步是解释这个字节为什么不被当前编码接受。标准 Base64 的字母表使用 + 和 /，URL-safe 变体使用 - 和 _；StdEncoding 和 URLEncoding 不能随意混用。另一个常见误判是把 = 后面的尾部垃圾当成“某个字符坏了”，实际上它属于填充完成后的额外输入。

例如，协议传的是无填充的 URL-safe Base64，就应明确写成 base64.RawURLEncoding；如果只是从标准编码字符串里删除 =，却继续使用带填充的编码器，错误会在输入末尾暴露。这个问题不是靠 strings.TrimRight(input, "=") 就能解决的，编码器选择必须与生产端协议一致。

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	// URL-safe 且无填充的输入，使用与协议匹配的 RawURLEncoding。
	src := "SGVsbG8td29ybGQ"
	data, err := base64.RawURLEncoding.DecodeString(src)
	if err != nil {
		fmt.Println("decode failed:", err)
		return
	}
	fmt.Println(string(data))

	// Strict 只额外检查末尾填充位，不会把换行变成非法字符。
	strict := base64.StdEncoding.Strict()
	_, err = strict.DecodeString("SGVsbG8=")
	if err != nil {
		fmt.Println("strict decode failed:", err)
	}
}

把偏移和上下文接到业务错误里

服务端日志通常需要让值班人员直接搜索原始消息，而不是只看到一段标准库错误。建议保留原始错误、偏移、输入总长度、编码变体和附近字节；原始数据可能包含令牌或个人信息时，只记录有限窗口，并按业务规则脱敏。

package main

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

func decodePayload(src string, enc *base64.Encoding) ([]byte, error) {
	data, err := enc.DecodeString(src)
	if err == nil {
		return data, nil
	}

	var corrupt base64.CorruptInputError
	if errors.As(err, &corrupt) {
		pos := int64(corrupt)
		// 记录定位信息，但不把整段可能含敏感数据的输入写进日志。
		fmt.Printf("base64 payload rejected: offset=%d length=%d encoding=%T\n",
			pos, len(src), enc)
	}
	// 用 %w 保留 errors.As 所需的原始错误链。
	return nil, fmt.Errorf("decode payload: %w", err)
}

上层如果只关心“输入无效”，可以用 errors.As 判断后返回统一的 400；如果要做数据修复，则应把偏移和原始消息交给隔离队列或人工处理。不要在服务端静默删除未知字符：那会改变签名、令牌或压缩数据的原始字节，排查结果也无法复现。

一份可直接照着走的检查清单

1. 保留原始输入，不先做全局替换或删除。
2. 用 errors.As 提取 base64.CorruptInputError，把它当作零基字节偏移。
3. 检查偏移附近的原始字节；输入有 UTF-8 时按 byte 计数，不要按中文字数计数。
4. 确认生产端使用的是标准、URL-safe、带填充还是 Raw 变体。
5. 检查 = 的位置、数量以及填充后是否还有尾部垃圾。
6. 只有在协议确实要求严格 RFC 4648 填充位时，才启用 Strict()。
7. 需要部分结果时使用 Decode 的 n，只读取 dst[:n]。
8. 修复后保留原始错误链，方便上层统一分类和重试策略。

常见追问

CorruptInputError 的位置从 0 还是从 1 开始？

按零基字节偏移理解。也就是说，输入第一个字节的位置是 0。展示给人看时可以额外输出“第 N+1 个字节”，但不要覆盖原始偏移。

为什么错误位置和我肉眼数的字符不一样？

标准库按字节扫描，换行会被忽略，多字节 UTF-8 字符还会占用多个字节。应先对原始 []byte(src) 数位置，再决定怎样转换为用户可读提示。

能不能把非法字符删掉后再解码？

除非协议明确规定允许忽略某类分隔符，否则不建议。删除字符可能让损坏的令牌、签名或压缩数据变成另一份数据；正确做法是确认生产端编码变体并拒绝不可恢复的输入。