当前位置：首页 > 文章列表 > 文章 > 前端 > Web Crypto API 如何导入与导出 AES-GCM 密钥：ArrayBuffer 编码、IV 管理与解密验收

Web Crypto API 如何导入与导出 AES-GCM 密钥：ArrayBuffer 编码、IV 管理与解密验收

来源：17golang原创 2026-08-27 08:50:41 0浏览收藏

前端把 AES-GCM 密钥放在 localStorage 里再直接传给 crypto.subtle.importKey()，最容易遇到的不是算法报错，而是数据类型和参数对不上：Base64 还是字节数组、密钥是否允许导出、IV 有没有每次重新生成。下面用一组可以在浏览器控制台运行的最小代码，把这些边界一次对齐。

要点速览

importKey() 接收的是明确的二进制格式，Base64 文本必须先解码成 ArrayBuffer。
AES-GCM 每次加密都要使用新的 12 字节 IV，IV 不需要保密，但必须随密文保存。
只有以 extractable: true 导入或生成的 CryptoKey 才能用 exportKey() 导出。
验收不能只看 Promise 没有报错，还要确认解密结果与原文逐字节一致。

先把浏览器里的数据边界分清

Web Crypto API 的接口围绕二进制工作。页面接口、JSON 和 localStorage 却更习惯保存字符串，所以实际接线通常是“字符串 → Base64 → Uint8Array → ArrayBuffer → CryptoKey”。反方向导出时再把字节转成 Base64。

对象	代码中的类型	适合保存的位置
原始密钥字节	ArrayBuffer / Uint8Array	内存或受控传输
可操作密钥	CryptoKey	CryptoKey 对象，不直接 JSON.stringify
密钥文本表示	Base64 字符串	接口字段或配置字段，需额外保护
初始化向量	12 字节 Uint8Array	与密文一起保存，不重复使用

Web Crypto API 中 Base64、Uint8Array、ArrayBuffer 与 CryptoKey 的数据边界示意，展示导入和导出方向

用 Base64 往返导入和导出 AES-GCM 密钥

先准备两个转换函数。这里使用浏览器原生 atob 和 btoa，它们处理的是字节字符串，不要把包含中文的普通 Unicode 文本直接塞进去。

function base64ToBytes(base64) {
  const binary = atob(base64);
  return Uint8Array.from(binary, ch => ch.charCodeAt(0));
}

function bytesToBase64(bytes) {
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
}

async function importAesKey(base64Key) {
  const raw = base64ToBytes(base64Key);
  if (![16, 24, 32].includes(raw.byteLength)) {
    throw new Error("AES key must be 128, 192, or 256 bits");
  }
  return crypto.subtle.importKey(
    "raw",
    raw,
    { name: "AES-GCM" },
    true,
    ["encrypt", "decrypt"]
  );
}

async function exportAesKey(key) {
  const raw = new Uint8Array(await crypto.subtle.exportKey("raw", key));
  return bytesToBase64(raw);
}

导入时的第四个参数是 extractable。如果传入 false，加解密仍然可以用，但之后调用 exportKey 会失败。导出能力只应在确有需要的边界打开，不能把它当作默认配置。

用唯一 IV 完成一轮加密和解密验收

AES-GCM 推荐使用 12 字节 IV。IV 可以公开保存，但同一把密钥下不能重复使用；因此每轮加密都重新调用 crypto.getRandomValues()。密文返回值已经包含认证标签，保存时可直接和 IV 一起编码。

async function encryptText(key, text) {
  const iv = crypto.getRandomValues(new Uint8Array(12));
  const data = new TextEncoder().encode(text);
  const ciphertext = await crypto.subtle.encrypt(
    { name: "AES-GCM", iv },
    key,
    data
  );
  return {
    iv: bytesToBase64(iv),
    ciphertext: bytesToBase64(new Uint8Array(ciphertext))
  };
}

async function decryptText(key, packet) {
  const iv = base64ToBytes(packet.iv);
  const ciphertext = base64ToBytes(packet.ciphertext);
  const plaintext = await crypto.subtle.decrypt(
    { name: "AES-GCM", iv },
    key,
    ciphertext
  );
  return new TextDecoder().decode(plaintext);
}

const keyText = "0123456789abcdef0123456789abcdef";
const key = await importAesKey(bytesToBase64(new TextEncoder().encode(keyText)));
const packet = await encryptText(key, "订单草稿 v3");
const restored = await decryptText(key, packet);
console.assert(restored === "订单草稿 v3", "AES-GCM round trip failed");
console.log({ packet, restored });