Kotlin 中字符串的 Base64 编码与解码指南

1. 概述

本文将介绍在 Kotlin 中对字符串进行 Base64 编码和解码的几种常用方法。

Base64 是现代 Web 应用中常见的数据编码方式，尤其适用于将二进制数据安全地以文本形式传输。无论你是处理 JWT Token、HTTP Basic 认证，还是嵌入图片资源，都可能踩过编码不一致的坑。本文帮你理清思路，避免掉坑。

2. Base64 基础原理

Base64 是一种将二进制数据转换为文本格式的编码方案。其核心思想是使用 64 个可打印字符来表示二进制内容，这 64 个字符包括：

✅ A-Z、a-z、0-9、+ 和 /

此外，填充符 = 用于补齐不足的字节。

⚠️ 注意：3 个字节（24 位）的原始数据，正好可以拆分为 4 个 6 位的组，对应 4 个 Base64 字符。如果原始数据长度不是 3 的倍数，则末尾补 = 进行填充。

以字符串 "Baeldung" 为例，其 Base64 编码过程如下：

1. 将每个字符转为 ASCII 码，再转为 8 位二进制
2. 将所有二进制位拼接后，每 6 位划分为一组
3. 每组 6 位对应 Base64 字符表中的一个索引，查表得到字符
4. 若最后不足 6 位，则补 0 并用 = 填充

最终结果为：

QmFlbGR1bmc=

下图展示了该过程的详细步骤：

另一个更详细的流程图：

通过上述分析，我们可以确认 "QmFlbGR1bmc=" 是 "Baeldung" 的正确 Base64 表示。

3. 使用 java.util.Base64

JDK 8 起内置了 java.util.Base64 工具类，无需引入第三方依赖，推荐优先使用。

✅ 编码示例

val originalString = "Baeldung"
val encodedString: String = Base64.getEncoder().encodeToString(originalString.toByteArray())
assertEquals("QmFlbGR1bmc=", encodedString)

• getEncoder() 返回符合 RFC4648 标准的编码器
• encodeToString() 直接返回字符串，比 encode() 更方便

✅ 解码示例

val encodedString = "QmFlbGR1bmc="
val decodedString: String = String(Base64.getDecoder().decode(encodedString))
assertEquals("Baeldung", decodedString)

• getDecoder() 返回标准解码器
• decode() 返回 byte[]，需手动转为 String

💡 提示：注意字符集问题！建议显式指定 charset，如 toByteArray(Charsets.UTF_8)，避免平台默认编码不一致导致乱码。

4. 使用 Apache Commons Codec

如果你的项目仍在使用 JDK 7 或以下版本，或者已经引入了 Apache Commons 工具库，也可以选择 commons-codec。

添加依赖

<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
</dependency>

导入类（注意命名冲突）

由于 org.apache.commons.codec.binary.Base64 与 java.util.Base64 同名，建议使用别名导入：

import org.apache.commons.codec.binary.Base64 as ApacheBase64

✅ 编码示例

val originalString = "Baeldung"
val base64: ApacheBase64 = ApacheBase64()
val encodedStr = String(base64.encode(originalString.toByteArray()))
assertEquals("QmFlbGR1bmc=", encodedStr)

✅ 解码示例

val encodedString = "QmFlbGR1bmc="
val base64: ApacheBase64 = ApacheBase64()
val decodedString: String = String(base64.decode(encodedString))
assertEquals("Baeldung", decodedString)

⚠️ 注意：

• encode() 返回 byte[]，需用 String() 构造函数转为字符串
• 同样建议指定字符集，避免隐式转换风险

5. 总结

本文介绍了 Kotlin 中实现 Base64 编码与解码的两种主流方式：

方式	是否需要依赖	推荐程度
java.util.Base64	❌ 不需要	✅ 强烈推荐（JDK 8+）
Apache Commons Codec	✅ 需要添加依赖	⚠️ 兼容旧项目时使用

最佳实践建议：

• ✅ 优先使用 java.util.Base64，轻量且标准
• ✅ 显式指定字符集（如 UTF-8），避免跨平台问题
• ✅ 处理用户输入或网络数据时，务必捕获 IllegalArgumentException（非法 Base64 字符）
• ❌ 不要自己实现 Base64 算法，容易出错且无必要

掌握这些基础工具的正确用法，能有效避免诸如“本地正常线上报错”这类经典踩坑场景。