Unicode 文本与 btoa/atob 乱码排查

这个页面解决什么问题

浏览器原生 btoa/atob 针对的是二进制字符串，不是任意 Unicode 文本。中文、日文、emoji、特殊符号如果直接传入 btoa，可能抛出异常或得到与预期不同的结果。正确流程是先把 Unicode 字符串编码成 UTF-8 字节，再进行 Base64 编码。

这个问题常见于前端把用户输入、配置文本、国际化文案、JSON 样本或 emoji 直接编码后发送给接口。英文测试可以通过，不代表多语言输入也正确。

快速判断

• 英文和数字能正常编码，中文或 emoji 报错，通常是 btoa 输入范围问题。
• 解码后出现乱码，优先检查编码端和解码端是否都按 UTF-8。
• 同一文本在不同工具得到不同 Base64，可能是字符集或换行不同。
• JSON 中的中文先 stringify 后编码，与直接编码原文不是同一输入。

可复制示例：错误输入与修复后输入

坏样例直接把中文传给 btoa；修复思路是先做 UTF-8 字节转换。

btoa("你好，Ymir 👋")

UTF-8 bytes("你好，Ymir 👋") -> Base64 -> decode bytes as UTF-8

工具页面如果声明支持 Unicode，应在内部处理 UTF-8。手写代码时必须显式处理字符到字节的转换，不能只依赖英文样本验证。

诊断步骤

1. 准备包含中文、空格、emoji 和换行的最小样本。
2. 用 Base64 工具 编码并立即解码，确认往返一致。
3. 在项目代码中检查是否直接调用 btoa/atob 处理 Unicode 字符串。
4. 确认服务端解码后按 UTF-8 读取，而不是按 Latin-1 或系统默认编码。
5. 对 JSON 文本先确定是编码原始文本，还是编码 stringify 后的 JSON 字符串。

乱码问题必须同时检查编码端和解码端。只在一端修复可能让样本看起来通过，但跨浏览器、跨语言或跨服务后再次失败。

常见错误表

常见误判

• 只用 ASCII 文本测试 Base64 功能。
• 把 URL 编码、Unicode 转义和 Base64 混为一谈。
• 解码出乱码后反复尝试 padding，而没有检查字符集。
• 把浏览器控制台显示的字符串与真实字节序列混淆。

多语言内容要用实际语言样本测试，不能只靠 “hello world”。文案、用户名、地址和通知模板尤其容易暴露字符集问题。

隐私、安全和适用边界

用于排查时请使用脱敏样本。不要粘贴访问令牌、Cookie、客户资料、内部域名、未公开商业规则、支付记录或完整生产日志。页面适合处理公开示例、教学片段、复现样本和已经替换真实值的配置。

本页讲的是字符编码，不处理加密、签名或压缩格式。如果 Base64 内容本来是图片、压缩包或密文，解码后不应期待得到可读文本。

复制或发布前复核清单

1. 样本是否包含中文、emoji、空格和换行。
2. 编码端是否明确使用 UTF-8。
3. 解码端是否按 UTF-8 还原文本。
4. 是否区分原始文本、JSON 字符串和转义文本。
5. 是否保留编码前后样本做往返验证。
6. 是否避免把真实用户输入公开到问题单。

相关工具和延伸阅读

参考依据

• MDN btoa()：输入字符限制。
• MDN TextEncoder/TextDecoder：Unicode 与 UTF-8 字节转换。
• RFC 4648：Base64 只定义字节到文本的表示。

编辑记录：Ymir Tool editorial review，2026-06-01。本页作为 Sprint 3 新增案例/排错内容发布，目标是把单一工具入口扩展为可复核的任务说明、错误示例和操作边界。