🧩 WebAssembly API 速查表（WebAssembly JS API Cheat Sheet）

🧩 WebAssembly API 速查表（WebAssembly JS API Cheat Sheet）

---

🧠 全局对象：WebAssembly

名称	类型	说明
WebAssembly.compile(bufferSource)	Promise<Module>	异步编译 ArrayBuffer 或 TypedArray 里的 wasm 字节码。
WebAssembly.compileStreaming(responsePromise)	Promise<Module>	边下载边编译。性能最优。
WebAssembly.instantiate(bufferSource, [importObject])	Promise<{module, instance}>	异步编译并实例化 wasm 模块。
WebAssembly.instantiateStreaming(responsePromise, [importObject])	Promise<{module, instance}>	边下载边编译并实例化。
WebAssembly.validate(bufferSource)	boolean	检查字节流是否是合法 wasm 模块。

---

🧱 构造器（类型对象）

构造器	主要属性 / 方法	说明
WebAssembly.Module	WebAssembly.Module.exports(module) WebAssembly.Module.imports(module)	已编译模块（无状态，可复用）。
WebAssembly.Instance	.exports	模块实例，包含导出函数、内存、表、全局变量等。
WebAssembly.Memory	.buffer (ArrayBuffer) .grow(pages)	线性内存（页大小 64 KB）。
WebAssembly.Table	.length .get(i) .set(i, func) .grow(n)	函数表（支持间接调用）。
WebAssembly.Global	.value	表示全局变量，可读写（若 mutable）。
WebAssembly.Tag 🆕	.type	异常类型（Exception Handling 提案）。
WebAssembly.Function 🆕	构造签名化 Wasm 函数	Typed Function References 提案。

---

⚙️ 错误类（Error Types）

错误类	触发场景
WebAssembly.CompileError	字节码非法或语法错误。
WebAssembly.LinkError	导入 / 导出不匹配。
WebAssembly.RuntimeError	运行时异常（越界访问、除 0 等）。

---

🪄 Promise 集成 (JSPI 提案)

名称	类型	说明
WebAssembly.Suspending(jsFunc)	构造器	把 JS 函数包装为“可挂起”的导入，允许 wasm 等待 Promise 完成。
WebAssembly.promising(wasmFunc)	函数	把 wasm 导出函数包装为返回 Promise 的异步函数。

示例

const imports = {
  env: { fetchData: new WebAssembly.Suspending(asyncFetch) }
};
const { instance } = await WebAssembly.instantiateStreaming(fetch("mod.wasm"), imports);
const runAsync = WebAssembly.promising(instance.exports.run);
await runAsync();

---

🧾 静态方法与辅助工具

名称	说明
WebAssembly.Module.imports(module)	获取模块导入列表。
WebAssembly.Module.exports(module)	获取模块导出列表。
WebAssembly.validate(bytes)	校验 wasm 二进制是否合法。

---

🧩 内部对象常用属性

对象	属性	类型	说明
Instance	.exports	object	导出表（函数、内存、全局、表）。
Memory	.buffer	ArrayBuffer	共享内存缓冲区。
	.grow(pages)	number	扩展内存页数。
Table	.length	number	当前函数表大小。
	.get(index) / .set(index, func)	function	读写表项。
Global	.value	any	当前全局变量值。

---

🧮 示例调用流程

// 加载并实例化
const { instance } = await WebAssembly.instantiateStreaming(fetch("test.wasm"), {
  env: { log: console.log }
});

// 调用导出函数
instance.exports.main();

// 访问内存
const mem = instance.exports.memory;
const bytes = new Uint8Array(mem.buffer, 0, 16);

---

🧱 实验性 / 草案提案（部分环境支持）

提案	新 API	功能说明
JSPI	Suspending, promising	Wasm 与 Promise 的互操作。
Exception Handling	Tag	原生异常支持。
Memory64	扩展 Memory 寻址范围	超 4 GB 线性内存。
Typed Function Refs	WebAssembly.Function	类型安全 JS → Wasm 函数引用。

---

🧾 总览表

分类	成员
编译与实例化	compile, compileStreaming, instantiate, instantiateStreaming, validate
类型对象	Module, Instance, Memory, Table, Global, Tag, Function
错误类型	CompileError, LinkError, RuntimeError
Promise 集成	Suspending, promising
辅助函数	Module.imports(), Module.exports()
内存 / 表操作	Memory.grow(), Table.get(), Table.set(), Table.grow()