Web Crypto API 不提供 Base64 编解码，需手动桥接；加密函数返回 ArrayBuffer，须用 Uint8Array + String.fromCharCode + btoa 转 Base64，大数组需分块；解码则用 atob + charCodeAt 填入 Uint8Array 还原 ArrayBuffer。
Web Crypto API 本身不提供 Base64 编码/解码功能——它只负责加密、哈希、密钥生成等密码学操作；Base64 编解码是独立的二进制 ↔ 字符串转换步骤，必须配合 TextEncoder/TextDecoder 或 Uint8Array 手动桥接。
为什么不能直接用 crypto.subtle.encode() 做 Base64
crypto.subtle 没有 encode() 这个方法（那是 Node.js 的 Buffer 方法）；常见误解是以为加密后输出自动是 Base64 字符串，其实它返回的是 ArrayBuffer 或 Uint8Array，需要你自己转。
- 加密函数如
encrypt()、sign()、digest()全部返回ArrayBuffer - 浏览器原生 Base64 转换只有两个可靠入口：
btoa()（仅支持 Latin-1 字节）和TextEncoder+Uint8Array+ 自行实现或借用ArrayBuffer工具函数 - 直接对中文、emoji 或任意二进制数据用
btoa()会报错或乱码，因为它的输入必须是单字节字符串
安全可靠的 Base64 编码：从 ArrayBuffer 到字符串
这是最常被调用的环节——比如你刚用 encrypt() 得到密文 ArrayBuffer，想存 localStorage 或发给后端，就得转成 Base64 字符串。
- 先用
new Uint8Array(arrayBuffer)把缓冲区转为字节数组 - 再逐字节转成 ASCII 码，拼成字符串传给
btoa()——但注意：这仅适用于纯 ASCII 字节；更通用的做法是用String.fromCharCode(...uint8Array)构造中间字符串（该字符串每个字符代表一个字节，可被btoa安全处理） - 推荐封装函数，避免每次重复写：
function arrayBufferToBase64(buffer) {
const bytes = new Uint8Array(buffer);
const str = String.fromCharCode(...bytes);
return btoa(str);
}
⚠️ 注意：String.fromCharCode(...bytes) 在大数组（如 >100KB）上可能触发 “maximum call stack size exceeded”，此时应改用循环或 Uint8Array 分块处理。
Base64 解码还原为 ArrayBuffer：供 crypto.subtle 后续使用
收到 Base64 字符串（比如从 API 获取的密文或公钥 PEM），要喂给 importKey() 或 decrypt()，就必须还原成 ArrayBuffer。
- 先用
atob()解出原始字符串（每个字符仍代表一个字节） - 再用
TextEncoder编码会出错——因为它把每个字符当 UTF-16 处理；正确做法是遍历字符串，用.charCodeAt(i)提取字节值，填入Uint8Array - 封装示例：
function base64ToArrayBuffer(base64) {
const binStr = atob(base64);
const len = binStr.length;
const bytes = new Uint8Array(len);
for (let i = 0; i < len; i++) {
bytes[i] = binStr.charCodeAt(i);
}
return bytes.buffer;
}
这个 ArrayBuffer 就能直接传给 crypto.subtle.importKey() 或 decrypt() 了。
实际组合场景：加密后 Base64 传输，再解码解密
典型链路是：明文 → 加密 → ArrayBuffer → Base64 字符串 → 发送；接收方 → Base64 → ArrayBuffer → 解密 → 明文 ArrayBuffer → TextDecoder 解码为字符串。
- 加密输出是
ArrayBuffer，不是 Base64，别指望encrypt()返回字符串 - 密钥导入（
importKey()）若用 JWK 格式，key_ops和alg必须匹配，否则decrypt()报OperationError - Base64 字符串若含换行或空格（比如 PEM 中的 -----BEGIN...），必须先
.replace(/[\r\n\s]/g, '')清理，否则atob()报InvalidCharacterError - 前端解密失败时，优先检查：Base64 是否损坏、
ArrayBuffer长度是否与算法要求一致（如 AES-GCM 密文含 12 字节 IV+密文+16 字节 authTag）、IV 是否被正确传递
真正容易卡住的地方，往往不在加密逻辑本身，而在 ArrayBuffer ↔ Base64 ↔ 字符串这几步的隐式编码假设上——尤其是跨语言对接时，后端用 Python 的 base64.b64encode() 输出是标准无换行 Base64，但前端若误用 btoa(unescape(encodeURIComponent(str))) 处理非 ASCII 文本，就会彻底对不上。
