btoa(encodeURIComponent(JSON.stringify(query))) 为何会因 Unicode 报错？

Question

`btoa(encodeURIComponent(JSON.stringify(query)))` 常因 Unicode 处理不当而报错（如 `DOMException: Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range`）。根本原因在于：`btoa()` 仅支持 ISO-8859-1（Latin-1）字符集，即每个字符必须对应 0–255 的单字节值；而 `encodeURIComponent()` 虽将非 ASCII 字符转为 UTF-8 编码的 `%XX` 形式（如中文 `"你好"` → `"%E4%BD%A0%E5%A5%BD"`），其返回结果仍是含 `%`、`E`、`4` 等 ASCII 字符的字符串——看似安全。但若原始 `query` 中包含未被 `encodeURIComponent` 覆盖的高代理对（surrogate pairs）、BOM、控制字符，或开发者误将已编码字符串重复传入 `btoa`，就可能混入 UTF-16 码点 > 255 的字符（如 `"\u{1F600}"` 表情符号在 JS 字符串中占两个 16 位码元）。此时 `btoa` 尝试按 UTF-16 字符逐字节编码，必然越界失败。正确解法是先 UTF-8 编码字符串再 base64（如用 `TextEncoder` + `btoa` 或现代 `btoa(String.fromCodePoint(...))` 配合严格预处理）。

Answer 1

```html

一、现象层：典型错误与复现路径

开发者常写：btoa(encodeURIComponent(JSON.stringify(query)))，在含中文、emoji（如 "😊"）、BOM（\uFEFF）或高代理对（如 "\uD83D\uDE00"）的 query 中抛出：
DOMException: Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range。

二、机制层：btoa 的字节契约与 JavaScript 字符模型错位

• btoa() 并非“Base64 编码字符串”，而是将传入字符串按 UTF-16 编码后的每个码元（code unit）视为 Latin-1 字节（0–255）直接映射；
• JavaScript 字符串是 UTF-16 编码序列，单个 Unicode 码点 ≥ U+10000（如 emoji 🌍 U+1F30D）需用两个 16 位代理码元（surrogate pair）表示；
• 当 encodeURIComponent() 处理含代理对的字符串时，其输出仍为合法 ASCII 字符串（%, 0-9, A-F），但若原始 query 已含未转义控制字符（如 \u0000）、BOM 或开发者误将已编码结果二次传入 btoa，则 JS 引擎会将高位码元（如 \uD83D = 55357 > 255）当作非法 Latin-1 字节触发异常。

三、验证层：最小可复现实例与诊断脚本

// ✅ 安全：纯 ASCII
btoa(encodeURIComponent(JSON.stringify({q: "hello"}))); // "eyJxIjoiSGVsbG8ifQ=="

// ❌ 崩溃：含 emoji（UTF-16 surrogate pair）
btoa(encodeURIComponent(JSON.stringify({q: "😊"}))); 
// → DOMException: btoa failed — 因内部字符串含 \uD83D（55357）等 >255 码元

// 🔍 诊断工具
function inspectString(s) {
  return Array.from(s).map(c => ({char: c, code: c.codePointAt(0), hex: c.codePointAt(0).toString(16)}));
}
console.log(inspectString("😊")); // [{char:"😊", code:128520, hex:"1f600"}]

四、解法层：三类生产级安全方案对比

方案	兼容性	安全性	代码体积	适用场景
TextEncoder + btoa	Chrome 63+/Firefox 68+/Edge 79+	✅ UTF-8 精确编码	轻量（原生 API）	现代浏览器主导项目
Buffer.from(str, 'utf8').toString('base64')（Node.js）	Node.js ≥ 6.0	✅ 原生 UTF-8 流式处理	零额外依赖	服务端/SSR 场景
polyfill + utf8.encode()（如 utf8.js）	IE11+	✅ 兼容所有环境	+3KB gzipped	需支持旧版浏览器

五、工程层：推荐实现与防御性封装

/**
 * 安全 Base64 编码：严格 UTF-8 → Base64，自动处理 surrogate pairs/BOM/控制字符
 * @param {any} input - 任意可 JSON 序列化的值
 * @returns {string} Base64-encoded UTF-8 bytes of JSON string
 */
function safeBtoa(input) {
  const jsonString = JSON.stringify(input);
  if (typeof TextEncoder === 'undefined') {
    throw new Error('TextEncoder not supported — use polyfill or fallback');
  }
  const encoder = new TextEncoder(); // UTF-8 encoder
  const uint8Array = encoder.encode(jsonString);
  // 将 Uint8Array 转为 Latin-1 字符串（每个字节 → 对应 ASCII 字符）
  const latin1String = String.fromCharCode(...uint8Array);
  return btoa(latin1String);
}

// 使用示例
safeBtoa({ q: "你好🌍😊", flag: true }); 
// → "eyJxIjoi5L2g5aW977yM77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB77yB7......"

六、演进层：现代替代方案与架构建议

在新项目中，应优先考虑：

• JWT 场景：直接使用 crypto.subtle.digest('SHA-256', ...) + base64url（非 base64）避免 padding 和 URL 不安全字符；
• API 签名/参数编码：改用 URLSearchParams 构建 query string，天然 UTF-8 安全且无需手动 base64；
• 前端持久化：对敏感结构化数据，采用 JSON.stringify() → CryptoJS.AES.encrypt(...).toString() 等端到端加密，而非仅 base64（base64 ≠ 加密）。

七、流程图：安全 Base64 编码执行路径

flowchart TD
  A[原始 query 对象] --> B[JSON.stringify\\n生成 UTF-16 字符串]
  B --> C{TextEncoder 可用？}
  C -->|是| D[TextEncoder.encode\\n→ Uint8Array \\nUTF-8 字节流]
  C -->|否| E[utf8.encode polyfill\\n→ Uint8Array]
  D --> F[String.fromCharCode\\n字节转 Latin-1 字符串]
  E --> F
  F --> G[btoa\\n标准 Base64 编码]
  G --> H[最终 Base64 字符串]

```