在 .NET 中使用 Base64 时容易踩的坑总结

前言

欢迎关注【dotnet研习社】，今天我们讨论的内容是" .NET 中使用 Base64 "。

在日常的 .NET 开发中，Base64 编码/解码是一个非常常见的需求，比如文件上传、令牌处理（JWT）、数据加密传输等。但它看似简单，实则暗藏不少坑点，尤其在跨平台、跨语言通信时尤为突出。

本文将从 .NET 中使用 Base64 编码的常见方式出发，深入分析几个容易踩坑的地方，并提供实用的解决方案。

一、基础回顾：Base64 的标准用法

csharp 复制代码

static void Main(string[] args)
{
    // 编码字符串为 Base64
    string text = "Hello, World!";
    byte[] bytes = Encoding.UTF8.GetBytes(text);
    string base64 = Convert.ToBase64String(bytes);
    Console.WriteLine($"原始字符串: {text}");
    Console.WriteLine($"Base64字符串:{base64}");
    // 解码 Base64 为字符串
    byte[] decodedBytes = Convert.FromBase64String(base64);
    string decodedText = Encoding.UTF8.GetString(decodedBytes);
    Console.WriteLine($"解码Base64:{decodedText}");
}

这段代码本身没有问题，但实际使用场景中，会遇到如下 真实世界的坑。

二、坑点 1：Base64 不是 URL 安全的

标准 Base64 使用字符集包括 +、/、=，这在 URL 中不安全：

+ 在 URL 中会被解读为空格；
/ 会被当作路径分隔符；
= 在查询参数中可能被丢弃或解释出错。

✅ 正确做法：使用 Base64Url 编码

Base64Url 是一种变体，使用 - 和 _ 替代 + 和 /，并去除尾部的 =：

csharp 复制代码

public static string Base64UrlEncode(byte[] input)
{
    return Convert.ToBase64String(input)
        .Replace("+", "-")
        .Replace("/", "_")
        .TrimEnd('=');
}

public static byte[] Base64UrlDecode(string input)
{
    string base64 = input.Replace("-", "+").Replace("_", "/");
    int pad = 4 - (base64.Length % 4);
    if (pad < 4) base64 = base64.PadRight(base64.Length + pad, '=');
    return Convert.FromBase64String(base64);
}

三、坑点 2：字符串和 Base64 不是一一对应的

很多人误以为 Base64 是字符串加密的"转换形式"，但它其实是对 字节数组 进行编码。

📌 举个例子：中文字符串在不同编码下的 Base64 会完全不同！

csharp 复制代码

  Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
  string cn = "你好";
  string base64Utf8 = Convert.ToBase64String(Encoding.UTF8.GetBytes(cn));
  string base64Gb2312 = Convert.ToBase64String(Encoding.GetEncoding("gb2312").GetBytes(cn));
  Console.WriteLine($"UTF-8: {base64Utf8}");
  Console.WriteLine($"GB2312: {base64Gb2312}");

输出对比如下：

✅ 正确做法：

在编码和解码字符串前，明确指定编码格式，避免跨平台乱码。

四、坑点 3：跨语言通信时 Padding（=）被丢失

标准 Base64 输出为长度为 4 的倍数，若不足会使用 = 填充。但很多 JavaScript、Go、Python 等库在 URL-safe 模式下会省略掉尾部 =。

如果你直接用 Convert.FromBase64String("SGVsbG8")，会抛异常！

✅ 正确做法：

手动补齐填充符：

csharp 复制代码

string base64 = "SGVsbG8"; // 无 =
int pad = 4 - (base64.Length % 4);
if (pad < 4) base64 = base64.PadRight(base64.Length + pad, '=');
byte[] decoded = Convert.FromBase64String(base64);

五、坑点 4：在 JSON 中嵌套 Base64 字符串

Base64 字符串可能包含 +、/、= 等特殊字符，若直接作为 JSON 字符串中的属性值传输，在前端解析时有概率被转义或破坏。

json 复制代码

{
  "data": "U29tZVRleHQ="
}

✅ 正确做法：

始终使用 Base64Url；
或使用 HttpUtility.UrlEncode 对字符串再次编码；
在前端/后端进行二次转码处理。

六、坑点 5：混用 Convert 和 HttpServerUtility/Base64 Web 编码

很多早期的 WebForm、ASP.NET MVC 中，曾使用如下写法：

csharp 复制代码

Server.UrlEncode(Convert.ToBase64String(...));

但 UrlEncode 会把 + 编成 %2B，在 HttpUtility.UrlDecode 解码时可能多出或少出字符，导致数据不一致。

✅ 正确做法：

不建议混用 Convert 和 UrlEncode；
用 Base64Url 或 JSON 原生 base64 序列化工具更稳妥。

七、总结：避免 Base64 使用误区的建议

问题	建议做法
Base64 不安全于 URL	使用 Base64Url
字符串编码不一致	显式指定 UTF-8 等编码
跨平台 Padding 不一致	手动补 `=`
JSON 中嵌套出错	做二次 UrlEncode 或使用 Base64Url
多语言 Base64 不兼容	确保标准统一（Base64Url + UTF-8）

结语

Base64 编码虽然常见，但在实际应用中，尤其是 Web 系统、移动端通信、JWT Token 解析等场景下，其坑点不容忽视。

如果在处理安全令牌、文件传输、图像数据封装、或跨平台通信中使用 Base64，务必牢记：

✅ Base64 是字节的编码，不是字符串的转换。

✅ Base64Url 是 Web 场景下的首选。

欢迎留言你遇到过哪些 Base64 坑，我们一起填坑 ✍️