Base64 编码排错指南：补位、Unicode、Data URL 与 API Payload

Base64 看起来很简单：输入内容，得到一串更长的 ASCII 字符。但实际开发里，Base64 出错往往不是算法错，而是补位缺失、URL-safe 字符集混用、复制了 Data URL 前缀、字符编码不一致，或者在错误的层级解码。

这篇指南按排错顺序说明如何定位问题。

Base64 到底在做什么

Base64 是把字节转换成 ASCII 字符，让二进制数据可以通过只接受文本的系统传输。常见场景包括：

Base64 不是加密。拿到字符串的人都可以解码。如果内容敏感，应先加密或使用安全传输通道，而不是依赖 Base64。

有些 “Base64 解码失败” 的根因更早：粘贴进来的内容根本不是 Base64。它可能是 URL 编码、JSON 字符串、十六进制转储、HTML 实体，或者一段看起来像编码的错误信息。

改代码前先看字符：

如果值来自 URL 参数，先解 URL 这一层。如果值来自 JSON，先单独取出字段值再解码。

标准 Base64 使用：

A-Z a-z 0-9 + /

URL-safe Base64 会替换两个字符：

+ 变成 -
/ 变成 _

JWT 和 URL 参数里经常使用 Base64URL，而且常常省略补位。把 JWT 片段直接放进严格的标准 Base64 解码器，可能会报错。此时要么使用 URL-safe 模式，要么先规范化字符集和补位。

Base64 常用 = 补位，使长度成为 4 的倍数：

TWFu
TWE=
TQ==

有些系统会省略补位，尤其是 URL-safe 编码。遇到 “invalid length” 或 “incorrect padding” 这类错误时，先数长度：

不要一上来就盲目补 =。先确认日志、复制、换行、数据库字段长度没有把字符串截断。

图片 Base64 经常以 Data URL 形式出现：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

逗号前面的部分只是描述 MIME 类型和编码方式，不是 Base64 内容。真正需要解码的是逗号后面的字符串。把整段一起解码，要么失败，要么得到无效字节。

排查图片上传时，确认三件事：

Base64 处理的是字节。文本必须先按 UTF-8 等编码转成字节，再进行 Base64 编码。中文、日文、Emoji 和很多符号，一个字符会占多个 UTF-8 字节。

如果发送方按 UTF-8 编码，接收方却按 Latin-1 或其他编码解释，Base64 字符串本身可能完全正确，但解码后的文本会乱码。

遇到乱码时，检查：

可以把 UTF-8 转换工具和 Base64 编码解码工具结合使用，同时检查字节和文本。

API 里的 Base64 字段失败时，按这个顺序排查：

这样能把传输层问题和业务逻辑问题分开。

JWT 的 header 和 payload 是 Base64URL 编码，但解码 JWT 不等于验证 JWT。JWT 的可读性是设计的一部分，真正的安全性来自签名验证。

调试 token 时，不要把生产 token 粘贴到不可信工具里。即使 payload 看起来合理，也必须通过签名验证后才能相信其内容。

出现非法字符错误，通常是包含空格、换行、URL 编码、Data URL 前缀，或标准/URL-safe 字符集混用。

出现长度错误，通常是缺少补位、字符串被截断，或复制时漏了字符。

图片能解码但打不开，通常是文件类型不匹配、把前缀一起解码，或编码前内容已损坏。

文本乱码，通常说明 Base64 是有效的，但原始字节被用错误的字符编码解释。

如果同一段输入在一个解码器里可用，在另一个解码器里失败，比较两者是否启用了严格模式。有些解码器会忽略空白和缺失补位，有些会按更严格规则直接报错。