解决JavaScript加密中文字符串出现乱码的问题

作者:缓存笔记时间:2026-11-21 18:32:46浏览:559

深入剖析JavaScript在对包含中文的字符串进行加密时产生乱码的根本机制,提供基于原生Web Crypto API和CryptoJS的标准解决方案、代码范例与排查对齐指南。

技术专题 阅读时长约 8 分钟 标准环境:Modern Browser / Node.js 16+
解决JavaScript加密中文字符串出现乱码的问题
图示:JavaScript 中文字符串多字节转换与加密链路概览
在 JavaScript 中对中文字符串进行加密(如 AES、RSA 或 Base64 编码)时,解密后出现乱码或直接抛出异常,根本原因在于加密算法底层处理的是二进制字节流,而 JavaScript 内部使用的是 UTF-16 字符单元。当程序未显式将包含多字节的中文字符串转换为标准 UTF-8 字节序列,而直接按单字节截断或前后端编码规则不一致时,就会发生字节错位导致乱码。解决该问题的标准路径是:加密前使用 TextEncoder(或加密库对应的 UTF-8 解析器)将中文字符串转为标准的 UTF-8 字节数组,解密后再通过 TextDecoder 将二进制字节数组还原为中文字符串。本文将针对这一核心问题,说明乱码产生的底层机制、不同主流工具的修复代码以及前后端对接排查对齐的完整步骤。

一、乱码产生的底层机制:为什么加密算法“不认识”中文?

在排查加密乱码时,首先需要区分“字符”与“字节”。现代加密算法(如 AES、DES、RSA)属于数学运算模型,它们在设计上只接收固定长度的二进制比特块或字节流(例如 16 字节的明文分组),并不感知上层自然语言是 ASCII 英文还是多语言汉字。

JavaScript 引擎在内存中以 UTF-16 编码存储字符串。对于 ASCII 范围内的英文字母(如 'A',码点 65),它只占用一个低 8 位字节;而常用中文字符(如 '中',码点 0x4E2D,十进制 20013)在 UTF-16 中占用 2 个字节,在 UTF-8 编码下则会被序列化为 3 个连续字节:0xE4、0xB8、0xAD。

解决JavaScript加密中文字符串出现乱码的问题
图 1:中文字符在 JavaScript 加密中的字节错位与乱码成因剖析

当开发者直接将含有中文的 JavaScript 字符串交给某些加密函数或原生工具(如 window.btoa())时,系统默认假设每个字符的码点都在 0x00 ~ 0xFF(即 Latin1 单字节范围)之内:

  • 报错崩溃场景:btoa("中文") 会直接抛出 DOMException: Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range.。
  • 字节截断乱码场景:部分旧式加密库在获取字节时,内部简单执行 str.charCodeAt(i) & 0xFF,强行丢弃了高位字节(例如 0x4E2D 丢弃高位 0x4E,仅剩 0x2D)。此时密文所加密的内容本身已经损坏,解密端无论如何也无法复原。
  • 解码分裂乱码场景:中文字符已按 UTF-8 正确加密成 3 字节,但解密端没有使用 UTF-8 解码器,而是使用类似 String.fromCharCode 逐个字节读取,导致 0xE4 0xB8 0xAD 被渲染成三个独立的西文字符 中(即典型的 Mojibake 乱码)。

二、容易混淆的常见说法与历史方案辨析

在解决该问题时,技术交流中经常出现两类看似合理但不够准确的说法,需要根据现代标准进行明确区分:

说法辨析一:“加密算法本身不支持中文,需要更换加密算法”

为什么看似合理:初学者直接把中文字符串传给加密函数时,往往报错或解密出乱码,更换某些包含自动转码特性的封装库后现象消失,容易得出算法不支持中文的推论。

成立条件与修正:算法数学本身完全独立于人类语言。无论 AES 还是 RSA,处理的都是纯净的二进制 Uint8Array 或 ArrayBuffer。只要在调用算法前将字符串编码为标准字节流,任何通用加密算法都能完美支持中文,不需要也不应该为了支持中文而更换加密算法。

说法辨析二:“用 encodeURIComponent 就能解决一切中文加密乱码”

为什么看似合理:在浏览器缺乏现代编码 API 的时期,开发者常用 btoa(unescape(encodeURIComponent(str))) 来规避 btoa 的报错。这是因为 encodeURIComponent 先将中文转为百分号形式(如 %E4%B8%AD),unescape 再将其转成单字节字符,从而安全通过 btoa。

成立条件与修正:该方案仅适用于纯纯的前端 Base64 编解码闭环,或者两端约定了非标准的 URI 字符映射。一旦与 Java、Go、Python 或 C# 后端标准加解密对接,这种做法会引入多余的字符开销与转义偏差。现代工程应优先使用标准的 TextEncoder 与 TextDecoder,直接输出合规的二进制字节数组。

三、标准解决流程:原生 Web Crypto API 实现

在现代浏览器与 Node.js 16+ 环境中,推荐直接使用 W3C 标准的 Web Crypto API。该规范要求所有加解密数据必须使用 BufferSource(如 Uint8Array),从接口层面杜绝了字符编码的不确定性。

解决JavaScript加密中文字符串出现乱码的问题
图 2:中文字符串加密与解密端到端标准处理步骤

1. 端到端实现代码(AES-GCM)

以下为完整的端到端中文字符串加密与解密实现,包含明文编码、向量生成、密文序列化以及逆向解码还原:

// 步骤 1:明文字符串转 UTF-8 字节流
function stringToUtf8Bytes(str) {
  const encoder = new TextEncoder();
  return encoder.encode(str); // 返回 Uint8Array
}

// 步骤 5 对应函数:UTF-8 字节流还原中文字符串
function utf8BytesToString(buffer) {
  const decoder = new TextDecoder("utf-8");
  return decoder.decode(buffer);
}

// 辅助工具:Uint8Array 与 Base64 互转(安全传输格式)
function bufferToBase64(buffer) {
  const bytes = new Uint8Array(buffer);
  let binary = "";
  for (let i = 0; i < bytes.byteLength; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return window.btoa(binary);
}

function base64ToBuffer(base64) {
  const binary = window.atob(base64);
  const bytes = new Uint8Array(binary.length);
  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }
  return bytes.buffer;
}

// 核心流程:加密函数
async function encryptChineseText(plainText, rawKeyBytes) {
  // 1. 将中文明文统一转为 UTF-8 Uint8Array
  const encodedData = stringToUtf8Bytes(plainText);

  // 2. 导入对称密钥(此处以 256 位 AES-GCM 为例)
  const cryptoKey = await crypto.subtle.importKey(
    "raw",
    rawKeyBytes,
    { name: "AES-GCM" },
    false,
    ["encrypt"]
  );

  // 3. 生成 12 字节的随机初始化向量 (IV)
  const iv = crypto.getRandomValues(new Uint8Array(12));

  // 4. 执行加密运算
  const cipherBuffer = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv: iv },
    cryptoKey,
    encodedData
  );

  // 5. 组合 IV 与密文并导出为 Base64 字符串用于传输
  return {
    iv: bufferToBase64(iv),
    cipherText: bufferToBase64(cipherBuffer)
  };
}

// 核心流程:解密函数
async function decryptChineseText(cipherObj, rawKeyBytes) {
  const iv = new Uint8Array(base64ToBuffer(cipherObj.iv));
  const cipherData = base64ToBuffer(cipherObj.cipherText);

  const cryptoKey = await crypto.subtle.importKey(
    "raw",
    rawKeyBytes,
    { name: "AES-GCM" },
    false,
    ["decrypt"]
  );

  // 1. 解密得到原始明文字节流 ArrayBuffer
  const decryptedBuffer = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv: iv },
    cryptoKey,
    cipherData
  );

  // 2. 将 UTF-8 字节流准确解码为中文字符串
  return utf8BytesToString(decryptedBuffer);
}
关键操作点说明

在上述代码中,stringToUtf8Bytes 与 utf8BytesToString 构成了防乱码的核心屏障。加密前通过 new TextEncoder().encode() 输出的 Uint8Array 保证了每个汉字对应合法的 3 字节序列;解密后通过 new TextDecoder().decode() 将字节序列一次性组装回 UTF-16 字符,避免了中间过程任何单字节丢弃。

四、主流第三方库的适配方案与代码示例

在很多现有项目中,可能依然广泛使用 CryptoJS 或针对 RSA 的 JSEncrypt。了解这些库内部的中文转换接口同样重要。

解决JavaScript加密中文字符串出现乱码的问题
图 3:主流 JavaScript 加密方案中文编码处理与常见误区对比

1. CryptoJS 中的正确用法

CryptoJS 内部使用专有的 WordArray 数据结构(32 位整数数组)。直接传入 JavaScript 字符串时,CryptoJS 的某些函数可能默认使用 Latin1 编码进行解析,导致中文字符高位被直接截断。

正确的做法是显式调用 CryptoJS.enc.Utf8.parse() 与 toString(CryptoJS.enc.Utf8):

// 需提前引入 crypto-js 库
// 1. 准备明文与密钥
const message = "用户隐私数据:北京市海淀区";
const secretKeyString = "16ByteSecretKey!"; // 16 字节密钥

// 2. 关键步骤:显式将中文字符串以 UTF-8 解析为 WordArray
const utf8Plaintext = CryptoJS.enc.Utf8.parse(message);
const utf8Key = CryptoJS.enc.Utf8.parse(secretKeyString);
const iv = CryptoJS.lib.WordArray.random(16); // 16 字节随机 IV

// 3. 加密操作(AES-CBC 模式,PKCS7 填充)
const encrypted = CryptoJS.AES.encrypt(utf8Plaintext, utf8Key, {
  iv: iv,
  mode: CryptoJS.mode.CBC,
  padding: CryptoJS.pad.Pkcs7
});

// 密文输出(Base64 格式字符串)
const cipherBase64 = encrypted.toString();
const ivBase64 = CryptoJS.enc.Base64.stringify(iv);

// 4. 解密操作
const decryptedCipher = CryptoJS.AES.decrypt(cipherBase64, utf8Key, {
  iv: CryptoJS.enc.Base64.parse(ivBase64),
  mode: CryptoJS.mode.CBC,
  padding: CryptoJS.pad.Pkcs7
});

// 5. 关键步骤:解密结果必须传入 CryptoJS.enc.Utf8 转换为字符串
// 若写成 decryptedCipher.toString(),默认返回十六进制字符串 Hex,而非明文
const originalText = decryptedCipher.toString(CryptoJS.enc.Utf8);

console.log("解密还原结果:", originalText); // 正常输出原中文

2. RSA(JSEncrypt)与长中文处理

使用 JSEncrypt 进行公钥加密时,中文字符串如果过长,不仅容易出现乱码,还会触发 Message too long for RSA 异常。

  • RSA-1024 配合 PKCS1Padding 填充时,单次最大加密明文长度为 128 - 11 = 117 个字节;
  • 一个英文字符占用 1 字节,而一个汉字占用 3 字节。因此 117 个字节只能容纳约 39 个汉字;
  • 如果在加密中文前未计算真实字节长度,而仅按 str.length 计算字符数,就会在超过字节上限时损坏密文并抛出解码错误。遇到长中文字符串时,应采用“AES 对称加密中文正文 + RSA 加密 AES 密钥”的混合加密架构。

五、前后端对接时的乱码排查与对齐清单

当 JavaScript 前端与 Java、Python、Go 等后端系统进行加密通信时,出现乱码往往不是单侧代码写错,而是两端约定存在微小偏差。遇到问题时,可对照以下四步清单进行结构化定位:

解决JavaScript加密中文字符串出现乱码的问题
图 4:加密中文字符串乱码问题排查与对齐四步法总结
检查阶段 前端(JavaScript)重点核对项 后端(Java/Python/Go)重点核对项 不一致导致的故障表现
1. 明文编码 是否通过 TextEncoder 转为 UTF-8 字节流 解密后是否使用 StandardCharsets.UTF_8 读取字符串 中文显示为 中文(西文乱码)或 ???
2. 密钥格式 Hex/Base64 是否已准确解析为原始二进制字节 key.getBytes(StandardCharsets.UTF_8) 与直接 Hex 解码是否混淆 解密直接抛出签名失败或 InvalidKeyException
3. 算法模式与填充 确认是 CBC 还是 GCM,是否配置了 PKCS7 填充 确认使用 AES/CBC/PKCS5Padding(与 PKCS7 兼容) 解密抛出 BadPaddingException(解密块损坏)
4. 密文传输协议 Base64 或 Hex 串,禁止直接传输未序列化二进制 传输层反序列化是否保持字节一致无字符截断 密文长度异常或 Base64 解码抛出非法字符异常

六、验证修复效果与边界场景测试

确认问题是否真正解决,不能只使用单个“测试”汉字验证,而应覆盖边界测试用例:

1. 边界用例清单

  1. 中文与 ASCII 混排:如 "Order#2026_订单状态:已支付_¥99.8",检验不同字节长度混合时的排版准确性。
  2. 生僻字与多字节 Unicode(4 字节):例如 "𪚥"(Unicode 码点 U+2A6A5)以及 Emoji 表情(如 "🔐🚀")。这类字符在 JavaScript 中由两个 UTF-16 代理对(Surrogate Pairs)组成,在 UTF-8 下占用 4 个字节,最能检验编码器是否完全合规。
  3. 空白字符与标点符号:全角空格( )、中文顿号、书名号等,确保不会被错误转义。

2. 往返一致性自动化验证脚本

// 验证测试脚本:在浏览器 Console 中直接运行验证
async function runEncodingVerifySuite() {
  const testCases = [
    "普通中文字符串测试",
    "中英混合 Test with numbers 123456 and symbols !@#$%",
    "生僻字与Emoji边界测试:𪚥 𠮷 🔐 🚀",
    "全角符号与换行:
【重要提示】	金额:¥100.00;全角空格: 结束。"
  ];

  // 生成测试用的 256 位随机密钥
  const testKey = crypto.getRandomValues(new Uint8Array(32));
  let passCount = 0;

  for (let i = 0; i < testCases.length; i++) {
    const original = testCases[i];
    try {
      // 执行加密与解密
      const encryptedData = await encryptChineseText(original, testKey);
      const decrypted = await decryptChineseText(encryptedData, testKey);

      if (original === decrypted) {
        console.log(`[PASS] 用例 ${i + 1} 验证通过: 长度 ${original.length} 字符`);
        passCount++;
      } else {
        console.error(`[FAIL] 用例 ${i + 1} 不匹配:
期望: "${original}"
实际: "${decrypted}"`);
      }
    } catch (err) {
      console.error(`[ERROR] 用例 ${i + 1} 执行抛出异常:`, err);
    }
  }

  console.log(`验证完成: 共 ${testCases.length} 项,通过 ${passCount} 项。`);
}

// 运行测试
runEncodingVerifySuite();
确认解决的核心指标

当上述测试套件中所有包含 Emoji、生僻字与复杂排版的用例均输出 [PASS],且控制台打印的 Uint8Array 字节长度符合预期时,即可确认当前系统的 JavaScript 中文字符加密链路已完全消除了乱码隐患。

作者最新文章
相关文章
更多