Web Crypto API仅在安全上下文（HTTPS或localhost）中可用，http或file://协议下调用会报SecurityError；crypto.subtle为undefined主因是环境不满足安全要求，需检查协议与域名。
Web Crypto API 不是 HTML 的一部分，而是浏览器 JavaScript 运行时提供的加密能力；你不能用 <script> 标签“引入”它，也不能在非安全上下文（如 http:// 或 file://）中调用它——直接调用会报 SecurityError: The operation is insecure.。
crypto.subtle 为什么 undefined 或报错
这是最常卡住的第一步。不是代码写错了，而是环境不满足最低要求：
- 必须运行在 HTTPS 协议下（
localhost也允许，但仅限开发） - 页面不能通过双击打开本地 HTML 文件（
file://路径） - iframe 嵌入时需显式声明
allow="encrypted-media"（极少数场景需要） - 某些旧版浏览器（如 IE、Safari < 16.4）根本不支持
crypto.subtle
验证方式很简单：console.log(window.crypto?.subtle) —— 若为 undefined，优先检查协议和域名。
AES-GCM 加密字符串必须做三件事
用 crypto.subtle.encrypt() 加密文本，光有密钥和数据远远不够。漏掉任一环节，解密必然失败：
立即学习“前端免费学习笔记（深入）”；
- 字符串必须先用
TextEncoder编码成Uint8Array，再转为ArrayBuffer（encrypt()只接受ArrayBuffer） -
iv必须是全新随机的Uint8Array(12)，且每次加密都不同；复用iv会导致密文可被推测 - 密钥必须有
"encrypt"权限，生成时得明确传入["encrypt", "decrypt"]（哪怕只加密不用解密，也要写上，否则后续无法导出或重用）
示例关键片段：
const encoder = new TextEncoder();
const data = encoder.encode("hello");
const iv = crypto.getRandomValues(new Uint8Array(12));
const key = await crypto.subtle.generateKey("AES-GCM", true, ["encrypt", "decrypt"]);
const encrypted = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key.key, data);
加密后怎么保存或传输才不会丢元数据
加密结果只是个 ArrayBuffer，但解密时缺不了 iv、salt（若用了 PBKDF2）、authTag（GCM 模式自动附带，但需手动提取）。常见错误是只存密文，上传或下载时丢掉 iv：
- 不要把
iv和密文拼成一个ArrayBuffer后再转 Base64 —— 容易错位，且无法区分边界 - 推荐用轻量 JSON 封装：
{ iv: btoa(String.fromCharCode(...iv)), data: btoa(String.fromCharCode(...encrypted)) } - 上传时用
FormData多字段提交，避免塞进 URL 或 header（易被日志截获） - 若下载为文件，建议构造新
Blob，把元数据放 JSON 字段里，密文放二进制主体，而非混在一起破坏 MIME 类型
为什么 Safari 解密总失败
不是你的代码有问题，而是 Safari 对 Web Crypto 的实现更保守：
- 它不支持
AES-CTR（截至 iOS 17.5 / macOS 14.5） - 它对
importKey()的格式校验更严格：若用deriveKey()派生密钥，importKey()的format必须是"raw"，且algorithm参数不能省略length - 它拒绝解密时传入未对齐的
iv长度（AES-GCM 要求 12 字节，少 1 字节就静默失败） - 它不支持从
jwk格式导入未设key_ops的密钥（必须显式包含["encrypt", "decrypt"]）
调试时加一句：console.log(await crypto.subtle.supportedAlgorithms)，确认目标算法是否在列表里。
真正容易被忽略的点是：密钥生命周期管理。Web Crypto 不提供持久化密钥存储，generateKey() 出来的密钥一旦离开作用域就丢了；而用户口令派生的密钥又必须每次重新计算——这意味着 IV、salt、密文、算法参数这四样东西，一个都不能少，且类型和顺序必须和加密时完全一致，否则解密就是黑盒失败。
