webassembly加密模块必须导出纯函数接口以确保确定性，避免gc干扰和内存拷贝，正确管理密钥生命周期并实现web crypto兜底。
WebAssembly 加密模块必须导出确定性函数接口
纯 JS 的 crypto-js 或自写 AES 实现在高并发或长密钥场景下容易卡顿，根本原因是 V8 对复杂循环和位运算的优化有限，且 GC 频繁干扰执行流。Wasm 模块要真正替代它，第一前提是导出的加密函数必须是纯函数：同一输入始终返回相同输出，不依赖全局状态或线性内存偏移。否则在多次调用中会出现密文不一致、IV 错位等静默错误。
实操建议：
- 用 Rust 实现时，禁用所有
std::time::Instant类时间依赖，避免非确定性行为 - Go 编译 Wasm 时需加
-gcflags="-N -l"关闭内联和优化干扰，确保调试符号不影响导出函数签名 - C 语言实现中，
aes_encrypt_block这类函数必须接收完整明文缓冲区指针和密钥指针，不能复用内部静态 buffer - 导出函数名必须带下划线前缀（如
_aes_gcm_encrypt），否则 Emscripten 默认不暴露
密钥与数据传递必须绕过 JS 内存拷贝
常见错误是把 Uint8Array 直接传给 Wasm 函数，触发 JS 引擎隐式复制——尤其处理 1MB+ 数据时，拷贝本身耗时可能超过加密本身。Wasm 线性内存是共享的，正确做法是让 JS 分配好内存视图，再把偏移地址传入。
实操建议：
- 初始化 Wasm 模块后，用
instance.exports.memory.buffer创建Uint8Array视图，统一管理输入/输出 buffer - 加密函数参数应为
(plaintext_ptr: i32, key_ptr: i32, out_ptr: i32, len: i32)，全部传地址而非值 - Rust 中使用
wasm-bindgen时，用#[wasm_bindgen(js_name = encrypt)]显式绑定，避免自动转换引入额外拷贝 - 避免在每次调用时调用
WebAssembly.instantiateStreaming，模块应预编译并缓存WebAssembly.Module实例
浏览器环境必须降级 fallback 到 Web Crypto API
不是所有用户都运行支持 Wasm SIMD 或多线程的现代浏览器。比如 Safari 16.4 之前不支持 WebAssembly.Global，某些企业内网 IE 兼容模式甚至无法加载 .wasm 文件。硬依赖 Wasm 会导致加密流程直接中断。
实操建议：
- 检测
typeof WebAssembly === 'object'且WebAssembly.validate(bytes)返回 true，才启用 Wasm 路径 - fallback 逻辑应直接调用
window.crypto.subtle.encrypt({ name: 'AES-GCM' }, key, data)，而非回退到 crypto-js - 密钥导入保持一致：Wasm 模块用 raw bytes，Web Crypto 用
importKey('raw', keyBytes, ...)，避免 base64/hex 转换引入偏差 - 不要在 Wasm 初始化失败时抛错终止，而是记录 warning 并静默切到 Web Crypto
敏感数据生命周期必须在 Wasm 内完成清理
JS 层无法控制 Wasm 线性内存中的残留数据。若加密后密钥或明文仍留在内存里，配合 Spectre 类侧信道攻击，可能被恶意脚本读取。这不是理论风险——已有 PoC 利用 performance.now() 计时差推测 Wasm 内存访问模式。
实操建议：
- Rust 中用
zeroizecrate 对密钥 buffer 调用.zeroize()，确保编译器不优化掉清零操作 - Go 编译 Wasm 时禁用 GC（
runtime.GC()不可用），改用unsafe手动覆写内存区域 - C 实现中，在
aes_encrypt_block返回前显式调用memset(state, 0, sizeof(state)) - 避免将密钥长期驻留 JS 全局变量，每次加密都从安全存储（如
SubtleCrypto.generateKey）临时派生
