crypto-js 中 MD5 和 SHA256 哈希算法的使用方法

一、安装与环境引入

在现代前端工程（Vite、Webpack、Rollup）与 Node.js 应用程序中，crypto-js 均提供了一致的调用 API。你可以通过包管理器安装完整的工具包：

# 使用 npm 安装
npm install crypto-js

# 或者使用 yarn 安装
yarn add crypto-js

1. 模块化项目中的引入方式

完整引入 crypto-js 会将 AES、DES、Rabbit、HMAC 以及各类哈希算法全部打包，体积相对较大。在实际生产项目中，推荐按需引入特定的算法子模块，以获得更好的 Tree-shaking 优化效果：

// 方案 A：全量引入（适合快速调试或 Node.js 环境）
import CryptoJS from 'crypto-js';

// 方案 B：按需引入（推荐，有效减小前端打包体积）
import md5 from 'crypto-js/md5';
import sha256 from 'crypto-js/sha256';
import encBase64 from 'crypto-js/enc-base64';
import encHex from 'crypto-js/enc-hex';

2. 浏览器环境通过 CDN 引入

如果是在没有构建工具的传统 HTML 页面或快速原型中，可直接引入 CDN 资源：

<!-- 引入完整库后，window.CryptoJS 全局可用 -->
<script src="https://cdn.jsdelivr.net/npm/crypto-js@4.2.0/crypto-js.min.js"></script>

二、MD5 哈希算法的基本用法与输出控制

MD5（Message Digest Algorithm 5）是一种产生 128 位（16 字节）哈希值的消息摘要算法。在 crypto-js 中，计算 MD5 非常直接：

import CryptoJS from 'crypto-js';

const rawText = 'Hello, crypto-js!';

// 计算 MD5
const hashResult = CryptoJS.MD5(rawText);

// 默认转为十六进制小写字符串 (Hex)
const hexString = hashResult.toString();
console.log('Hex (32位十六进制):', hexString);
// 示例输出: 5885f80fc05a9c97b2be4fa59d332616

1. 深入理解 WordArray 返回值

调用 CryptoJS.MD5(...) 时，返回的并不是普通的 JavaScript 字符串，而是一个 CryptoJS.lib.WordArray 对象。该对象是 crypto-js 内部用于统一管理二进制字节流的核心数据结构：

• words：一个 32 位整数数组（32-bit unsigned integers），每项包含 4 个字节数据。
• sigBytes：表示该二进制缓冲中真正有效的字节总数（避免末尾填充干扰有效数据）。

如果不调用 .toString() 或格式化转换函数，你将得到一个包含内部数据结构的 Object，无法直接传给后端或做文本匹配。

2. 控制输出编码：Hex 与 Base64

.toString() 方法在不传参时默认等价于 .toString(CryptoJS.enc.Hex)。若业务规范要求 Base64 格式输出，只需传入 CryptoJS.enc.Base64 编码器：

// 1. 默认十六进制输出 (Hex)
const md5Hex = hashResult.toString(CryptoJS.enc.Hex);
console.log('Hex 长度:', md5Hex.length); // 固定 32 字符

// 2. 转为大写十六进制（部分 Java / C# 后端默认规范要求大写）
const md5UpperHex = md5Hex.toUpperCase();

// 3. 输出 Base64 编码字符串
const md5Base64 = hashResult.toString(CryptoJS.enc.Base64);
console.log('Base64 结果:', md5Base64); // 示例: WIL4D8BanJeyvk+lnTMmFg==

三、SHA256 哈希算法的使用与接口签名实战

SHA256 属于 SHA-2（Secure Hash Algorithm 2）家族，生成的摘要固定为 256 位（32 字节）。相比 MD5，SHA256 具有目前密码学认可的极高抗碰撞能力，广泛应用于现代接口防篡改、区块链账本与密码存储前置哈希。

1. 基础调用与输出示例

import CryptoJS from 'crypto-js';

const payload = 'action=query&userId=10086&timestamp=1730347200';

// 计算 SHA256 摘要
const sha256Digest = CryptoJS.SHA256(payload);

// 默认转为十六进制字符串（64 字符小写）
const signHex = sha256Digest.toString();
console.log('SHA256 Hex 结果 (64 字符):', signHex);

// 转为 Base64 字符串
const signBase64 = sha256Digest.toString(CryptoJS.enc.Base64);
console.log('SHA256 Base64 结果:', signBase64);

2. 接口参数防篡改签名 (Sign) 封装范例

在日常 Web 交互中，最常见的场景是将请求参数进行 ASCII 字典序排序，拼接上安全密钥或时间戳后生成 SHA256 签名，附带在 HTTP 请求头中：

/**
 * 生成请求防篡改签名
 * @param {Record<string, any>} params 请求参数字典
 * @param {string} secretKey 服务端约定的秘钥
 * @returns {string} 64位十六进制哈希签名
 */
function generateSignature(params, secretKey) {
  // 1. 过滤空值并按 key 字母升序排列
  const sortedKeys = Object.keys(params)
    .filter(k => params[k] !== undefined && params[k] !== null && params[k] !== '')
    .sort();

  // 2. 拼接为 key=value 键值对
  const queryString = sortedKeys
    .map(k => `${k}=${params[k]}`)
    .join('&');

  // 3. 末尾附加秘钥盐值 (Salt)
  const stringToSign = `${queryString}&key=${secretKey}`;

  // 4. 计算 SHA256 并输出小写十六进制
  return CryptoJS.SHA256(stringToSign).toString();
}

// 测试调用
const requestParams = {
  appId: 'wx123456789',
  nonce: '8d7f2a1b',
  timestamp: 1730347200,
  amount: 99.5
};
const sign = generateSignature(requestParams, 'MY_SECRET_KEY_9988');
console.log('生成签名:', sign);

四、加盐哈希与 HMAC 算法升级

直接对密码或敏感字段进行单次 MD5 或 SHA256 哈希存在严重的“彩虹表查询”安全隐患。由于常见弱密码（如 123456、password）对应的哈希值已经被大规模预计算并录入公开数据库，攻击者可以在瞬间逆查原始明文。

1. 为什么必须加盐（Salt）？

“盐”是一段具有足够随机性、不可预测且长度合适的附加字符串。当我们在原始明文上拼接盐值后再进行哈希运算时，生成的哈希值将完全脱离常见彩虹表的收录范围，极大增加离线暴力破解的成本。

2. 使用 HMAC-SHA256 进行标准化加密钥哈希

纯文本拼接盐（如 text + salt）容易因为前后顺序、分隔符歧义或特定长度扩展攻击出现漏洞。更标准、更安全的工程方案是使用 HMAC（Hash-based Message Authentication Code，基于哈希的消息验证码）。crypto-js 原生内置了对 HMAC 的支持：

import CryptoJS from 'crypto-js';

const message = 'POST /api/v1/order {"goodsId":8899,"qty":2}';
const secretKey = 'Secure_Secret_Token_2026';

// 使用 HMAC-SHA256 算法
const hmacDigest = CryptoJS.HmacSHA256(message, secretKey);

// 转换为 Base64 或 Hex
const hmacSignBase64 = hmacDigest.toString(CryptoJS.enc.Base64);
const hmacSignHex = hmacDigest.toString(CryptoJS.enc.Hex);

console.log('HMAC-SHA256 (Base64):', hmacSignBase64);
console.log('HMAC-SHA256 (Hex):', hmacSignHex);

五、开发中常见陷阱与前后端联调排错

在实际业务落地过程中，前端通过 crypto-js 生成的哈希值与后端（如 Java、Go、Python 或 PHP）计算的结果不一致，是出现频次极高的问题。以下是核心排查清单：

1. 中文字符与字符编码不一致

crypto-js 默认将传入的字符串视为 UTF-8 编码处理。如果你的后端服务（例如历史遗留的 Java 或 C# 项目）使用了 GBK 或 ISO-8859-1 编码解析文本字节，那么对于包含汉字、日文或特殊符号的字符串，哈希值必然无法对齐。

2. 十六进制输出的大小写差异

crypto-js 的 .toString() 输出的十六进制哈希字符串全为小写字符（如 5885f80fc...）。而部分后端框架或第三方支付平台要求 32 位/64 位大写字符串（如 5885F80FC...）。如果在比对前没有做忽略大小写处理（.toLowerCase()），将直接导致签名校验失败。

3. 非字符串输入的隐式转换陷阱

当直接将 JavaScript 对象、数字或布尔值传给 CryptoJS.MD5(data) 时，如果未经过 JSON.stringify 或显式 String() 转换，JavaScript 可能会将其隐式转换为 "[object Object]"。这会导致不同内容的对象计算出来的哈希完全相同：

// 错误示范：隐式转换引发假哈希
const dataA = { name: 'Alice' };
const dataB = { name: 'Bob' };
console.log(CryptoJS.MD5(dataA).toString()); // 实际上计算的是 "[object Object]" 的哈希！
console.log(CryptoJS.MD5(dataB).toString()); // 输出完全一致！

// 正确做法：必须转为确定性的规范字符串
const safeHash = CryptoJS.MD5(JSON.stringify(dataA)).toString();

4. 空格与换行符问题

操作系统换行符的差异（Windows 为 ，Linux/macOS 为 ）会导致多行文本在不同机器上计算出的哈希截然不同。在进行长文本校验时，应先对换行符进行统一归一化替换：text.replace(/ /g, ' ')。

六、MD5 与 SHA256 算法对比与选型指南

很多开发者在设计新功能时容易困惑：究竟何时该用 MD5，何时必须使用 SHA256？

七、总结

在前端与 Node.js 体系中，crypto-js 为哈希计算提供了简单一致的调用体验。牢记以下关键要点，能够避免绝大多数线上问题：

• 统一引入规范：在现代前端打包工具中，优先使用 import md5 from 'crypto-js/md5' 与 import sha256 from 'crypto-js/sha256' 按需引入，减少包体体积。
• 理解 WordArray：算法执行后输出的是 WordArray 对象，必须显式调用 .toString()（默认转十六进制）或 .toString(CryptoJS.enc.Base64) 转换为文本。
• 排查首选编码与大小写：前后端联调哈希值不一致时，优先核对是否统一使用 UTF-8 编码，以及十六进制输出的大小写是否对齐。
• 明确安全边界：MD5 仅用于非安全场景的数据指纹与缓存校验；涉及接口签名、防篡改及用户凭据时，必须采用 SHA256 结合加盐（Salt）或标准的 HMAC-SHA256 机制。