使用 @aws-sdk/util-base64：AWS SDK for JavaScript v3 的 base64 编解码实用指南

@aws-sdk/util-base64 是 AWS SDK for JavaScript v3 内置的本地实用工具包，提供 toBase64() 与 fromBase64() 两个函数，用于在标准 base64 文本与原始字节（Uint8Array）之间互相转换。本指南完整覆盖该包的安装、初始化、五种常见编解码工作流、关键陷阱与 base64url 互操作方案，帮助你在 SDK v3 应用中可靠地处理字符串、二进制数据与字节边界的转换。

本指南对应的文档位于 content/aws/docs/util-base64/javascript/DOC.md，是 Context Hub 中 AWS 内容（JavaScript 语言变体）的一部分。Context Hub 以"版本化、按语言拆分"的方式维护这类文档，Agent 或开发者可通过 chub get aws/util-base64 --lang js 获取（参见 README.md 与 docs/content-guide.md 中关于多语言文档结构的说明）。

包的定位与适用场景

在 AWS SDK v3 代码中，当需要在标准 base64 字符串和原始字节之间转换时，使用本包。它对外暴露两个辅助函数：

• toBase64()：将 UTF-8 字符串或 Uint8Array 编码为 base64 文本；
• fromBase64()：将 base64 字符串解码为 Uint8Array。

这是一个本地工具包：它不会创建 AWS 服务客户端、不会加载凭证，也不读取任何包专属的环境变量。它的职责仅限于数据格式转换，请求发送、签名、重试等能力仍由对应的 SDK 客户端（如 @aws-sdk/client-s3）负责。

安装

安装你的项目所期望的版本即可。本指南对应的版本为 3.374.0：

npm install @aws-sdk/util-base64@3.374.0

建议与其他 AWS SDK v3 包保持匹配的版本号，避免跨版本的不兼容风险。

初始化

本包没有任何环境变量、凭证或客户端对象需要初始化。直接导入辅助函数即可使用：

import { fromBase64, toBase64 } from "@aws-sdk/util-base64";

如果项目仍在使用 CommonJS，也可以使用 require() 方式导入（与本仓库中同目录的 @aws-sdk/util-utf8 文档 content/aws/docs/util-utf8/javascript/DOC.md 所展示的导入模式一致）。

常见工作流

将 UTF-8 字符串编码为 base64

toBase64() 接受 JavaScript 字符串，并编码其 UTF-8 字节：

import { toBase64 } from "@aws-sdk/util-base64";

const encoded = toBase64("hello world");

console.log(encoded);
// aGVsbG8gd29ybGQ=

当应用边界需要的是文本形式的 base64 而非原始字节时（例如写入配置文件、日志或作为参数传递），使用这种方式。

编码二进制数据

当值已经是二进制时，直接传入 Uint8Array：

import { toBase64 } from "@aws-sdk/util-base64";

const bytes = Uint8Array.from([0xde, 0xad, 0xbe, 0xef]);
const encoded = toBase64(bytes);

console.log(encoded);
// 3q2+7w==

在 Node.js 环境中，Buffer 同样可用，因为它本身就是 Uint8Array 的子类。

将 base64 解码为字节

fromBase64() 返回原始字节，类型为 Uint8Array：

import { fromBase64 } from "@aws-sdk/util-base64";

const bytes = fromBase64("aGVsbG8gd29ybGQ=");

console.log(bytes);
// Uint8Array([...])

将 base64 解码为文本

如果解码出的字节确实表示 UTF-8 文本，则用 TextDecoder 将其转为字符串：

import { fromBase64 } from "@aws-sdk/util-base64";

const bytes = fromBase64("aGVsbG8gd29ybGQ=");
const text = new TextDecoder().decode(bytes);

console.log(text);
// hello world

注意：fromBase64() 本身只返回字节，不会自动帮你转成字符串。是否使用 TextDecoder 取决于解码内容的实际语义——只有确认字节是 UTF-8 文本时才需要解码。

从 ArrayBuffer 开始编码

toBase64() 的入参类型是 string | Uint8Array。如果代码中持有的是 ArrayBuffer，需要先用 new Uint8Array(...) 包装：

import { toBase64 } from "@aws-sdk/util-base64";

const arrayBuffer = new Uint8Array([1, 2, 3, 4]).buffer;
const encoded = toBase64(new Uint8Array(arrayBuffer));

console.log(encoded);

重要陷阱

使用本包时请特别留意以下边界行为：

• fromBase64() 期望的是标准 base64，而不是 base64url。输入中若使用了 - 和 _ 字符，必须在解码前先规范化（见下文"Base64url 互操作"）。
• fromBase64() 对非法字符和不正确的填充会直接拒绝，而不是尝试自行修复恢复。因此上游数据必须先经过校验。
• toBase64() 只接受字符串或 Uint8Array。ArrayBuffer 必须先用 new Uint8Array(...) 包装再传入。
• fromBase64() 返回的是字节而非字符串。仅当解码结果确实是 UTF-8 文本时，才使用 TextDecoder 转换。
• toBase64("...") 编码的是字符串的 UTF-8 字节。如果你手头已经是二进制数据，请直接传入 Uint8Array，而不要先把字节转成 JavaScript 字符串再编码——那会引入不必要的编码往返，甚至可能破坏字节内容（尤其是非 Latin-1 范围的高字节数据）。

Base64url 互操作

如果另一个系统提供的是 base64url 编码（URL 安全的变体，使用 - 和 _ 代替 + 和 /，且通常省略填充），需要先规范化再调用 fromBase64()：

import { fromBase64 } from "@aws-sdk/util-base64";

const fromBase64Url = (input) => {
  const normalized = input
    .replace(/-/g, "+")
    .replace(/_/g, "/")
    .padEnd(Math.ceil(input.length / 4) * 4, "=");

  return fromBase64(normalized);
};

const bytes = fromBase64Url("aGVsbG8td29ybGQ");
console.log(new TextDecoder().decode(bytes));

这段代码做了三件事：将 - 替换回 +、将 _ 替换回 /，并按照 4 字符一组的对齐规则补齐 = 填充，从而把 base64url 输入还原为标准 base64 后再交给 fromBase64()。这是与 JWT、URL query 参数等场景互操作时最常见的预处理步骤。

版本说明

本指南基于 @aws-sdk/util-base64 版本 3.374.0。在较新的 AWS SDK v3 内部实现中，类似的 base64 辅助函数也可能由 @smithy/util-base64 提供，但面向应用层的使用方式不变：编码用 toBase64()，解码用 fromBase64()。保持包版本与你的 SDK 客户端一致，即可获得稳定的行为。