更新记录

1.1.0（2025-11-25） 下载此版本

✨ 新功能

• 添加完整的 TypeScript 类型定义文件 (crypto.d.ts)
• 添加完整的测试套件 (tests/crypto.test.js)
• 添加可视化测试页面 (example/test-page.vue)

1.0.0（2025-08-31） 下载此版本

v1.0.0

初始版本发布

支持AES加密解密

支持多种哈希算法

提供工具函数

平台兼容性

uni-app(4.07)

uni-app x(4.07)

其他

hy-plugin-crypto-js

基于 CryptoJS 的 Uniapp 加密解密插件，支持多种加密算法和哈希算法

✨ 特性

• 🔐 AES 加密解密 - 支持多种模式和填充方式
• 🔑 哈希计算 - MD5、SHA256、SHA512
• ✍️ HMAC 签名 - 支持多种哈希算法
• 📦 工具函数 - Base64 编解码、随机密钥/IV 生成
• 🎯 TypeScript 支持 - 完整的类型定义
• 🌍 全平台支持 - H5、App、各类小程序
• 🆓 完全免费 - 开源无广告

📦 安装

方式一：通过 uni_modules（推荐）

在 HBuilderX 中直接从插件市场导入，或手动将 uni_modules 文件夹复制到项目根目录。

方式二：通过 npm

npm install crypto-js
# 如需 TypeScript 支持
npm install -D @types/crypto-js

🚀 快速开始

JavaScript 使用

// 引入加密服务
import cryptoService from '@/uni_modules/hy-plugin-crypto-js/js_sdk/crypto.js';

// AES 加密
const encrypted = cryptoService.aesEncrypt('Hello World', '1234567890123456');
console.log('加密结果:', encrypted);

// 解密数据
const decrypted = cryptoService.aesDecrypt(encrypted, '1234567890123456');
console.log('解密结果:', decrypted);

TypeScript 使用

import cryptoService from '@/uni_modules/hy-plugin-crypto-js/js_sdk/crypto.js';
import type { AESOptions } from '@/uni_modules/hy-plugin-crypto-js/js_sdk/crypto';

// 类型安全的加密
const options: AESOptions = {
  iv: '1234567890123456',
  mode: cryptoService.modes.CBC,
  padding: cryptoService.paddings.Pkcs7
};

const encrypted = cryptoService.aesEncrypt('Hello World', '1234567890123456', options);

📖 API 文档

AES 加密/解密

aesEncrypt(data, key, options?)

加密数据，返回 Base64 格式的密文。

参数：

• data (string | object) - 待加密数据，支持字符串和对象
• key (string) - 密钥，长度必须是 16/24/32 字节
• options (object, 可选) - 加密选项
  • iv (string) - 初始化向量
  • mode - 加密模式（CBC/CFB/CTR/OFB/ECB）
  • padding - 填充方式（Pkcs7/Iso97971/AnsiX923等）

示例：

// 基础加密
const encrypted1 = cryptoService.aesEncrypt('Hello', '1234567890123456');

// 加密对象
const encrypted2 = cryptoService.aesEncrypt(
  { username: 'admin', password: '123456' },
  '1234567890123456'
);

// 自定义选项
const encrypted3 = cryptoService.aesEncrypt('Hello', '1234567890123456', {
  iv: '1234567890123456',
  mode: cryptoService.modes.CBC,
  padding: cryptoService.paddings.Pkcs7
});

⚠️ 重要说明：

• 当使用 CBC/CFB/CTR/OFB 模式但未提供 IV 时，插件会自动使用密钥作为 IV
• 建议显式提供 IV 以获得更好的安全性
• 加密和解密时必须使用相同的 IV

aesDecrypt(encryptedData, key, options?)

解密数据，自动识别并解析 JSON 对象。

参数：

• encryptedData (string) - Base64 格式的加密数据
• key (string) - 密钥，必须与加密时相同
• options (object, 可选) - 解密选项，必须与加密时相同

示例：

// 基础解密
const decrypted1 = cryptoService.aesDecrypt(encrypted1, '1234567890123456');

// 解密对象（自动解析 JSON）
const decrypted2 = cryptoService.aesDecrypt(encrypted2, '1234567890123456');
console.log(decrypted2.username); // 'admin'

哈希计算

md5(data) / sha256(data) / sha512(data)

计算数据的哈希值。

示例：

// MD5 哈希
const md5Hash = cryptoService.md5('Hello World');
console.log(md5Hash); // "b10a8db164e0754105b7a99be72e3fe5"

// SHA256 哈希
const sha256Hash = cryptoService.sha256('Hello World');

// SHA512 哈希
const sha512Hash = cryptoService.sha512('Hello World');

// 对象哈希
const objHash = cryptoService.md5({ id: 1, name: 'test' });

HMAC 签名

hmac(data, key, algorithm?)

生成 HMAC 签名。

参数：

• data (string | object) - 待签名数据
• key (string) - 密钥
• algorithm (string, 可选) - 算法：'MD5' | 'SHA1' | 'SHA256' | 'SHA512'，默认 'SHA256'

示例：

// 默认 SHA256
const signature1 = cryptoService.hmac('message', 'secret-key');

// 指定算法
const signature2 = cryptoService.hmac('message', 'secret-key', 'MD5');
const signature3 = cryptoService.hmac('message', 'secret-key', 'SHA512');

// API 签名示例
const apiParams = { id: 1, timestamp: Date.now() };
const signature = cryptoService.hmac(apiParams, 'api-secret-key', 'SHA256');

实用工具

base64Encode(data) / base64Decode(encodedData)

Base64 编解码。

// 编码
const encoded = cryptoService.base64Encode('Hello World');
console.log(encoded); // "SGVsbG8gV29ybGQ="

// 解码
const decoded = cryptoService.base64Decode(encoded);
console.log(decoded); // "Hello World"

generateRandomKey(length?) / generateRandomIV(length?)

生成随机密钥或 IV。

// 生成 AES-128 密钥（16字节）
const key16 = cryptoService.generateRandomKey(16);

// 生成 AES-256 密钥（32字节，默认）
const key32 = cryptoService.generateRandomKey(32);

// 生成随机 IV（16字节，默认）
const iv = cryptoService.generateRandomIV(16);

// 使用随机密钥和 IV
const randomKey = cryptoService.generateRandomKey(16);
const randomIV = cryptoService.generateRandomIV(16);
const encrypted = cryptoService.aesEncrypt('data', randomKey, { iv: randomIV });

💡 实际应用场景

1. 本地存储加密

// 加密存储敏感数据
const saveSecureData = (key, data) => {
  const secretKey = '1234567890123456'; // 实际使用时应从安全位置获取
  const encrypted = cryptoService.aesEncrypt(data, secretKey);
  uni.setStorageSync(key, encrypted);
};

// 读取并解密
const getSecureData = (key) => {
  const encrypted = uni.getStorageSync(key);
  const secretKey = '1234567890123456';
  return cryptoService.aesDecrypt(encrypted, secretKey);
};

2. API 请求签名

// 生成 API 签名
const generateApiSignature = (params) => {
  const sortedParams = Object.keys(params)
    .sort()
    .map(key => `${key}=${params[key]}`)
    .join('&');

  return cryptoService.hmac(sortedParams, 'api-secret', 'SHA256');
};

// 发送请求
uni.request({
  url: 'https://api.example.com/data',
  data: {
    id: 1,
    timestamp: Date.now(),
    signature: generateApiSignature({ id: 1, timestamp: Date.now() })
  }
});

3. 密码加密存储

// 注册时加密密码
const registerUser = (username, password) => {
  const salt = cryptoService.generateRandomKey(16);
  const hashedPassword = cryptoService.sha256(password + salt);

  // 存储用户信息
  saveUser({
    username,
    password: hashedPassword,
    salt
  });
};

// 登录验证
const verifyPassword = (username, inputPassword) => {
  const user = getUser(username);
  const hashedInput = cryptoService.sha256(inputPassword + user.salt);
  return hashedInput === user.password;
};

⚠️ 安全注意事项

密钥管理

❌ 不要这样做：

// 永远不要硬编码密钥！
const key = '1234567890123456'; // 危险！

✅ 推荐做法：

// 从环境变量或服务器获取
const key = process.env.CRYPTO_KEY;

// 或使用用户密码派生
const key = cryptoService.sha256(userPassword).substring(0, 32);

密钥长度

• AES-128: 16 字节（128 位）
• AES-192: 24 字节（192 位）
• AES-256: 32 字节（256 位）- 推荐

IV（初始化向量）

• 对于相同的明文和密钥，使用相同的 IV 会产生相同的密文
• 建议每次加密使用随机生成的 IV
• IV 可以公开传输，但不应重复使用

// 推荐：每次使用随机 IV
const iv = cryptoService.generateRandomIV(16);
const encrypted = cryptoService.aesEncrypt(data, key, { iv });
// 将 IV 和密文一起传输：iv + ':' + encrypted

🔧 常见问题

Q: 解密失败怎么办？

A: 检查以下几点：

1. 密钥和 IV 是否与加密时完全一致
2. 加密模式和填充方式是否匹配
3. 密文是否完整（未被截断或修改）

Q: 如何选择加密模式？

A:

• CBC (推荐) - 最常用，安全性好
• ECB - 不推荐，相同明文产生相同密文
• CTR - 适合流数据加密
• CFB/OFB - 适合实时数据加密

Q: TypeScript 类型提示不生效？

A: 确保已安装类型定义：

npm install -D @types/crypto-js

Q: 小程序平台报错？

A: 某些小程序平台可能需要额外配置，请在 manifest.json 中添加：

{
  "mp-weixin": {
    "optimization": {
      "subPackages": true
    }
  }
}

📊 支持的平台

🛠️ 支持的算法

对称加密

• AES (Advanced Encryption Standard)

哈希算法

• MD5 (不推荐用于安全场景)
• SHA1 (不推荐用于安全场景)
• SHA256 (推荐)
• SHA512 (推荐)

HMAC

• HMAC-MD5
• HMAC-SHA1
• HMAC-SHA256 (推荐)
• HMAC-SHA512

编码

• Base64
• Hex
• Utf8

📝 更新日志

查看 CHANGELOG.md

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

💬 联系方式

• 插件市场: hy-plugin-crypto-js
• GitHub Issues: 欢迎反馈问题