Web Crypto API 实战：浏览器端数据加密与安全处理完全指南

浏览器能做加密吗？答案是不仅能，而且在很多场景下应该做。Web Crypto API 是 W3C 标准的浏览器原生加密接口，支持哈希、对称加密、非对称加密、数字签名和密钥派生，所有运算都在本地完成，密钥不出浏览器。据统计，截至 2026 年主流浏览器对 Web Crypto API 的支持率已超过 97%，但大多数前端项目仍在依赖第三方库处理加密逻辑——这既是安全隐患，也是性能浪费。

🔐 一、Web Crypto API 核心能力与架构

Web Crypto API 通过 window.crypto 全局对象暴露，核心是 SubtleCrypto 接口（通过 crypto.subtle 访问）。之所以叫 “Subtle”，是因为它刻意设计为低层级原语，不提供"一键加密"的高级封装，而是让你精确控制每一步操作。

📌 **记住：**Web Crypto API 是异步的（返回 Promise），这与大多数加密库的同步 API 不同。异步设计避免了加密运算阻塞主线程，在处理大文件时尤为重要。

1.1 支持的算法全景

⚠️ **警告：**永远不要使用 AES-CBC 而不配合 HMAC 做完整性校验。直接用 AES-GCM，它同时提供加密和认证（AEAD），是现代应用的默认选择。

1.2 与 crypto-js 等库的对比

很多项目用 crypto-js 做前端加密，但 Web Crypto API 在多个维度有明显优势：

⚡ **关键结论：**新项目应直接使用 Web Crypto API，不再需要 crypto-js。唯一例外是需要 SHA-3 或 SM2/SM4 等国密算法时，仍需第三方库。

🚀 二、实战：从哈希到完整加密工作流

2.1 哈希计算：文件校验与数据指纹

哈希是最基础也最常用的能力。下面实现一个通用的哈希计算函数，支持大文件分块处理：

// 通用哈希计算：支持字符串、ArrayBuffer、文件
async function calculateHash(data, algorithm = 'SHA-256') {
  let buffer;
  
  if (typeof data === 'string') {
    buffer = new TextEncoder().encode(data);
  } else if (data instanceof ArrayBuffer) {
    buffer = data;
  } else if (data instanceof File) {
    // 大文件：使用流式读取避免内存溢出
    buffer = await data.arrayBuffer();
  } else {
    throw new Error('Unsupported data type');
  }
  
  const hashBuffer = await crypto.subtle.digest(algorithm, buffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

// 使用示例
const sha256 = await calculateHash('Hello, Web Crypto!');
// => "a1f3b2c4d5e6f7..." (64 字符)

const file = document.querySelector('input[type="file"]').files[0];
const fileHash = await calculateHash(file);
// => 可用于文件去重、完整性校验

💡 **提示：**SHA-256 的输出是 256 位（32 字节），转为十六进制字符串后固定 64 个字符。SHA-1 输出 40 字符，SHA-512 输出 128 字符。MD5 不被 Web Crypto API 支持——这是刻意的，因为 MD5 已不安全。

2.2 AES-GCM 对称加密：保护敏感数据

AES-GCM 是当前最推荐的对称加密模式。下面实现一个完整的加密/解密工具，包含随机 IV 生成和认证标签：

// AES-GCM 加密工具类
class AESGCMCipher {
  static async generateKey() {
    return crypto.subtle.generateKey(
      { name: 'AES-GCM', length: 256 },
      true,  // extractable: true 允许导出密钥
      ['encrypt', 'decrypt']
    );
  }

  static async encrypt(plaintext, key) {
    // 12 字节随机 IV（AES-GCM 标准要求）
    const iv = crypto.getRandomValues(new Uint8Array(12));
    const encoded = new TextEncoder().encode(plaintext);
    
    const ciphertext = await crypto.subtle.encrypt(
      { name: 'AES-GCM', iv, tagLength: 128 },
      key,
      encoded
    );
    
    // 将 IV 和密文拼接存储（IV 不需要保密）
    const combined = new Uint8Array(iv.length + ciphertext.byteLength);
    combined.set(iv);
    combined.set(new Uint8Array(ciphertext), iv.length);
    
    // 返回 Base64 编码
    return btoa(String.fromCharCode(...combined));
  }

  static async decrypt(ciphertextBase64, key) {
    const combined = Uint8Array.from(atob(ciphertextBase64), c => c.charCodeAt(0));
    const iv = combined.slice(0, 12);
    const ciphertext = combined.slice(12);
    
    const decrypted = await crypto.subtle.decrypt(
      { name: 'AES-GCM', iv, tagLength: 128 },
      key,
      ciphertext
    );
    
    return new TextDecoder().decode(decrypted);
  }
}

// 使用示例
const key = await AESGCMCipher.generateKey();
const encrypted = await AESGCMCipher.encrypt('敏感数据：用户手机号 13800138000', key);
const decrypted = await AESGCMCipher.decrypt(encrypted, key);
console.log(decrypted); // => "敏感数据：用户手机号 13800138000"

⚠️ **警告：**永远不要复用 IV（初始化向量）。每次加密都必须生成新的随机 IV，否则 AES-GCM 的认证机制会被破坏，攻击者可能恢复明文。

2.3 从密码派生密钥：PBKDF2 实战

用户只记得密码，不可能直接给你一个 256 位密钥。PBKDF2 可以从用户密码安全地派生出加密密钥：

// 从用户密码派生 AES-GCM 密钥
async function deriveKeyFromPassword(password, salt) {
  // 第一步：将密码导入为原始密钥材料
  const passwordKey = await crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(password),
    'PBKDF2',
    false,
    ['deriveKey']
  );
  
  // 第二步：使用 PBKDF2 派生 AES-GCM 密钥
  return crypto.subtle.deriveKey(
    {
      name: 'PBKDF2',
      salt: salt,
      iterations: 600000,  // OWASP 2024 推荐值（针对 PBKDF2-SHA256）
      hash: 'SHA-256'
    },
    passwordKey,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt']
  );
}

// 完整使用流程
const password = '用户输入的密码';
const salt = crypto.getRandomValues(new Uint8Array(16));
const key = await deriveKeyFromPassword(password, salt);

// 加密后，将 salt 和密文一起存储
// 解密时，用相同的 salt + 密码重新派生密钥
const encrypted = await AESGCMCipher.encrypt('需要保护的数据', key);

💡 提示：iterations 参数决定了暴力破解的难度。600,000 次是 OWASP 2024 年对 PBKDF2-SHA256 的推荐值。如果你的场景允许，优先考虑 Argon2（但 Web Crypto API 不原生支持，需要 WASM 实现）。

2.4 密钥持久化：用 IndexedDB 安全存储密钥

生成的密钥如果不持久化，页面刷新后就丢失了。Web Crypto API 原生支持将密钥存储到 IndexedDB：

// 密钥存储管理器
const KeyStore = {
  DB_NAME: 'crypto-key-store',
  STORE_NAME: 'keys',
  
  async openDB() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(this.DB_NAME, 1);
      request.onupgradeneeded = () => {
        request.result.createObjectStore(this.STORE_NAME);
      };
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  },
  
  async saveKey(name, key) {
    const db = await this.openDB();
    const tx = db.transaction(this.STORE_NAME, 'readwrite');
    tx.objectStore(this.STORE_NAME).put(key, name);
    return new Promise((resolve, reject) => {
      tx.oncomplete = () => resolve();
      tx.onerror = () => reject(tx.error);
    });
  },
  
  async loadKey(name) {
    const db = await this.openDB();
    const tx = db.transaction(this.STORE_NAME, 'readonly');
    const request = tx.objectStore(this.STORE_NAME).get(name);
    return new Promise((resolve, reject) => {
      request.onsuccess = () => resolve(request.result);
      request.onerror = () => reject(request.error);
    });
  }
};

// 使用示例：生成密钥并持久化
const key = await AESGCMCipher.generateKey();
await KeyStore.saveKey('my-encryption-key', key);

// 页面刷新后恢复密钥
const restoredKey = await KeyStore.loadKey('my-encryption-key');

⚠️ **警告：**IndexedDB 中的密钥可以被同源的任何页面脚本访问。如果页面存在 XSS 漏洞，密钥也会暴露。因此，XSS 防护是使用 Web Crypto API 的前提。

💡 三、性能基准与生产最佳实践

3.1 性能实测：Web Crypto vs crypto-js

以下是在 Chrome 126 中对 1MB 数据的哈希计算性能测试结果：

数据越大数据差距越明显——Web Crypto API 调用的是浏览器底层的 C++ 加密实现，而 crypto-js 是纯 JavaScript，大数据量下性能劣势显著。

3.2 生产环境避坑指南

经过在多个项目中使用 Web Crypto API，以下是实战中总结的关键经验：

❌ 错误写法 vs ✅ 正确写法：

// ❌ 错误：同步方式处理，大数据会阻塞主线程
function hashSync(data) {
  // crypto-js 的做法
  return CryptoJS.SHA256(data).toString();
}

// ✅ 正确：使用原生异步 API + 分块处理大文件
async function hashLargeFile(file, chunkSize = 1024 * 1024) {
  const reader = file.stream().getReader();
  const hasher = await crypto.subtle.digest('SHA-256', new ArrayBuffer(0));
  // 实际场景需要用 Incremental Hash（见下文技巧）
}

对于超大文件（>100MB），推荐使用流式哈希避免一次性加载到内存：

// 流式哈希：使用 HMAC 模拟增量哈希（Web Crypto API 无原生 incremental digest）
async function streamHash(file) {
  // HMAC-SHA256 with zero key 等价于 SHA-256（对于哈希用途）
  const key = await crypto.subtle.importKey(
    'raw',
    new Uint8Array(32), // 全零密钥
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );
  
  const reader = file.stream().getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // 注意：这是简化示例，实际的流式 HMAC 需要更复杂的实现
  }
  
  // 生产环境建议使用 @noble/hashes 库的流式 API
}

⚠️ **警告：**Web Crypto API 没有原生的增量哈希（incremental digest）接口。对于超大文件，建议使用 @noble/hashes 等支持流式处理的库，或在 Service Worker 中使用 crypto.subtle.sign('HMAC', ...) 的分块更新能力。

3.3 实际应用场景案例

场景一：前端文件上传前的内容校验

用户上传文件前，先计算 SHA-256 哈希，与服务端比对判断是否已存在（秒传）：

// 文件秒传检测
async function checkFileExists(file) {
  const hash = await calculateHash(file);
  const response = await fetch('/api/files/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ hash, size: file.size })
  });
  const { exists } = await response.json();
  
  if (exists) {
    showToast('文件已存在，秒传成功！'); // 使用 jsjson 的 useToast
    return true;
  }
  return false;
}

场景二：本地数据加密存储

在「本地处理不上传服务器」的场景下（比如 jsjson.com 的在线工具），用 AES-GCM 加密用户数据后存入 localStorage 或 IndexedDB，即使设备被入侵，数据也不会泄露：

// 加密存储用户配置
async function secureStore(key, data) {
  let cryptoKey = await KeyStore.loadKey('user-data-key');
  if (!cryptoKey) {
    cryptoKey = await AESGCMCipher.generateKey();
    await KeyStore.saveKey('user-data-key', cryptoKey);
  }
  const encrypted = await AESGCMCipher.encrypt(JSON.stringify(data), cryptoKey);
  localStorage.setItem(key, encrypted);
}

// 解密读取
async function secureRetrieve(key) {
  const cryptoKey = await KeyStore.loadKey('user-data-key');
  if (!cryptoKey) return null;
  const encrypted = localStorage.getItem(key);
  if (!encrypted) return null;
  const decrypted = await AESGCMCipher.decrypt(encrypted, cryptoKey);
  return JSON.parse(decrypted);
}

场景三：SubtleCrypto 生成 JWT 签名

完全在浏览器端生成和验证 JWT（适用于无服务端的 PWA 场景）：

// 生成 RSA 密钥对并签名 JWT
async function generateJWT(payload, expiresIn = 3600) {
  const keyPair = await crypto.subtle.generateKey(
    {
      name: 'RSASSA-PKCS1-v1_5',
      modulusLength: 2048,
      publicExponent: new Uint8Array([1, 0, 1]),
      hash: 'SHA-256'
    },
    true,
    ['sign', 'verify']
  );
  
  const header = { alg: 'RS256', typ: 'JWT' };
  const now = Math.floor(Date.now() / 1000);
  const claims = { ...payload, iat: now, exp: now + expiresIn };
  
  const encode = obj => btoa(JSON.stringify(obj))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
  
  const data = `${encode(header)}.${encode(claims)}`;
  const signature = await crypto.subtle.sign(
    'RSASSA-PKCS1-v1_5',
    keyPair.privateKey,
    new TextEncoder().encode(data)
  );
  
  const sigBase64 = btoa(String.fromCharCode(...new Uint8Array(signature)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
  
  return { token: `${data}.${sigBase64}`, publicKey: keyPair.publicKey };
}

🔒 四、安全注意事项与常见陷阱

使用 Web Crypto API 时，有几个容易踩的坑必须注意：

1. ✅ 始终使用 AES-GCM 而非 AES-CBC — GCM 提供认证加密（AEAD），CBC 模式下攻击者可以通过 Padding Oracle 攻击恢复明文。

2. ✅ IV 必须随机且不复用 — 使用 crypto.getRandomValues() 生成 IV，每次加密都用新的。AES-GCM 下 IV 复用会导致认证标签失效。

3. ❌ 不要在客户端存储长期敏感密钥 — 浏览器环境本质上不可信。长期密钥应存在服务端，客户端仅做临时加解密。

4. ✅ 导出密钥时使用 JWK 格式 — crypto.exportKey('jwk', key) 返回标准 JSON 格式，方便传输和存储，比 raw 格式更灵活。

5. ⚠️ 注意跨浏览器差异 — Safari 在某些算法参数上的实现与其他浏览器略有不同，务必在目标浏览器上测试。

6. ✅ 配合 CSP 增强安全 — 设置 Content-Security-Policy 头防止 XSS，这是 Web Crypto API 安全模型的基础。

📝 总结

Web Crypto API 是现代前端安全的基石。相比第三方加密库，它零依赖、高性能、密钥不可导出（默认），并且是 W3C 标准。核心使用原则：

• 哈希用 crypto.subtle.digest('SHA-256', data)
• 对称加密用 AES-GCM + 随机 IV
• 非对称加密用 RSA-OAEP
• 签名验证用 RSASSA-PKCS1-v1_5 或 ECDSA
• 密钥派生用 PBKDF2（iterations ≥ 600,000）
• 密钥存储用 IndexedDB

⚡ **关键结论：**Web Crypto API 已经足够成熟，可以覆盖前端 90% 以上的加密需求。新项目不再需要引入 crypto-js、jsencrypt 等第三方库。唯一需要第三方库的场景是国密算法（SM2/SM4）或增量哈希。

相关工具推荐：

• jsjson.com 在线哈希计算工具 — 支持 MD5/SHA-256 等多种哈希算法
• jsjson.com RSA 加密工具 — 在线 RSA 密钥生成与加解密
• jsjson.com JSON 格式化工具 — 本地处理，数据不上传服务器
• @noble/hashes — 纯 JS 实现的高质量哈希库
• @noble/ciphers — 纯 JS 实现的 AES-GCM 等加密算法