JavaScript 原生 btoa 处理中文与 Emoji 报 InvalidCharacterError 根因与 UTF-8 转码

一、问题概述：btoa 的 Latin-1 字符集硬性边界

浏览器原生 window.btoa() 函数诞生于早期的 ASCII 时代，其规范强制要求输入字符串的每个字符码点必须在 U+0000 至 U+00FF 范围（即 Latin-1 字符集）。当输入包含中文（如 '中' 码点 U+4E2D）或 Emoji（如 '👋' 码点 U+1F600）时，btoa 无法直接将其切割为单字节，因而抛出 InvalidCharacterError 异常。

二、最小复现：对 Unicode 文本直接调用 btoa 抛出异常

下面的 JavaScript 代码展示了直接调用 btoa 导致的崩溃及其捕获过程：

try {
  /* 包含中文字符，超出 Latin-1 (0-255) 范围 */
  window.btoa("Hello 世界!");
} catch (e) {
  console.error(e);
  // DOMException: Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range.
}

三、根因分析：字节流转换与字符编码映射的缺失

Base64 本质是对二进制字节序列进行每 6-bit 的分组映射。btoa 假设每个 JS CharCode 直接对应 1 个 Byte。但现代 JS 使用 UTF-16 编码，中文字符在 UTF-8 下占用 3 个字节。直接将 UTF-16 字符传给 btoa 造成了“字符码点”与“底层字节”的严重错位。另外需要强调：Base64 仅是可逆的文本编码机制，绝对不能当成加密手段。

四、推荐方案：使用 TextEncoder / TextDecoder 进行字节中转

1. 编码流程：首先使用 TextEncoder 将 Unicode 字符串转换为 UTF-8 Uint8Array 字节数组，再将每个字节转化为 Latin-1 单字节字符后传给 btoa。2. 解码流程：使用 atob 获取二进制字符串，转换为 Uint8Array 字节数组，最后由 TextDecoder 还原 Unicode 文本。3. Node.js 环境直接使用 Buffer.from(str, 'utf-8').toString('base64')。

五、完整代码：跨环境 Unicode Base64 编解码纯函数

下面的 TypeScript 代码示范如何安全地编解码包含中文、日文与 Emoji 的任意 Unicode 字符串。

function unicodeToBase64(str: string): string {
  // 1. 将 Unicode 字符串转为 UTF-8 字节数组
  const bytes = new TextEncoder().encode(str);
  // 2. 将字节数组转为 Latin-1 单字节字符序列
  let binString = "";
  for (let i = 0; i < bytes.length; i++) {
    binString += String.fromCharCode(bytes[i]);
  }
  // 3. 调用原生 btoa 编码
  return btoa(binString);
}

function base64ToUnicode(base64: string): string {
  const binString = atob(base64);
  const bytes = Uint8Array.from(binString, function (char) {
    return char.charCodeAt(0);
  });
  return new TextDecoder().decode(bytes);
}

const originalText = "Hello 世界! 👋";
const encoded = unicodeToBase64(originalText);
console.log(encoded); // "SGVsbG8g5LiW55WMISDwn5iA"
console.log(base64ToUnicode(encoded)); // "Hello 世界! 👋"

六、常见错误方案

使用已被废弃且性能低下、无法完美支持 UTF-16 补充平面的 encodeURIComponent + unescape Hack 技巧；企图通过 Base64 隐藏敏感密码而不使用 AES/RSA 加密。

七、边界条件：高位 Unicode 代理对与 Emoji 4 字节字符

处理含有复杂组合 Emoji（如 family 或 🏴‍☠️ 旗帜）时，必须通过 TextEncoder 生成标准 UTF-8 字节流，切忌用 split('') 拆分字符串导致代理对被破坏。

八、如何验证 Unicode Base64 兼容性

断言 base64ToUnicode(unicodeToBase64(text)) === text；覆盖空串、中日韩文字、Emoji、组合字符、未配对 surrogate 与较大输入，并明确非法 Base64 的异常行为。

九、FAQ

问：为什么 btoa 设计成只支持 Latin-1？答：btoa（Binary to ASCII）最初设计目的就是处理 8-bit 二进制数据串，而非处理高级语言的多字节 Unicode 文本。

问：Base64 编码能防范爬虫或用于密码存储吗？答：不能！Base64 没有任何秘钥机制，任何人都可以直接 atob 还原明文，密码存储必须使用 Argon2id / bcrypt 哈希。

问：旧版浏览器没有 TextEncoder 怎么办？答：现代所有主流浏览器及 Node.js 11+ 均已原生支持；旧环境可引入 fast-text-encoding Polyfill。

十、总结

对中文与 Emoji 进行 Base64 编码的本质是“Unicode -> UTF-8 字节 -> Base64 字符”。使用 TextEncoder 和 TextDecoder 是现代 JavaScript 标准可靠的处理方案。