@taobao-minigame/binaryen

基于 Binaryen 132 的 Node.js 工具包，用于 WebAssembly 热冷分包及 Table ID 路由转换。

这是独立维护的封装和修改版构建，不是 Binaryen 官方发行包，也不代表上游项目的背书。

版本与运行环境

| 项目 | 版本或要求 | | --- | --- | | 本包版本 | 以安装包的 package.json 为准，与上游版本独立 | | Binaryen 上游源码 | version_132 | | Binaryen JavaScript API | 精确依赖 [email protected] | | wasm-split 构建工具链 | Emscripten 4.0.14 | | Node.js | >=16.20.2 |

工具通过 Node.js 子进程运行随包 JS/Wasm，不要求安装宿主平台的原生 Binaryen 可执行文件。

安装

npm install @taobao-minigame/binaryen

使用

下面保存为 .mjs 文件运行。profile.data 必须由匹配输入 Wasm 的插桩采集流程生成，不能用于其他构建的 Wasm。

import fs from 'node:fs/promises';
import tools from '@taobao-minigame/binaryen';

const { splitWasm, convertTableIdDispatch } = tools;
const wasm = await fs.readFile('./input.wasm');
const profile = await fs.readFile('./profile.data');

const { primary, secondary } = await splitWasm({ wasm, profile });
const converted = await convertTableIdDispatch({ primary });

await fs.writeFile('./primary.wasm', converted.primary);
await fs.writeFile('./secondary.wasm', secondary);
console.log(converted.stats);

也支持 CommonJS 入口：

const { splitWasm, convertTableIdDispatch, toolchainVersion } =
  require('@taobao-minigame/binaryen');

如需使用固定版本的 Binaryen JavaScript API：

import binaryen from '@taobao-minigame/binaryen/api.mjs';

API

| API | 输入 | 返回值 | | --- | --- | --- | | splitWasm({ wasm, profile }) | 两个 Uint8Array（包含 Node.js Buffer） | Promise<{ primary, secondary }>，两个 Wasm 字节数组 | | convertTableIdDispatch({ primary }) | Primary Wasm 的 Uint8Array | Promise<{ primary, stats }>，转换后的字节数组与统计信息 | | toolchainVersion | 无 | 描述底层工具产物的字符串，可用于缓存键，不等同于 npm 包版本 |

index.d.ts 提供封装 API 的类型声明。转换会将 placeholder 聚合为按签名共享的 Table ID 路由；Secondary Wasm 不经过该转换。

行为与限制

• 本包负责离线分包和转换，不负责 Profile 采集、分包下载、宿主加载或共享 Table 的运行时链接；接入方需要实现匹配的加载与链接逻辑。
• 必须保留 patches/portable-profile-hash.patch 的 signed-byte uint64 哈希约定，不能以跳过 Profile 校验代替兼容处理。
• 转换器遇到不支持的表达式会报错，不承诺支持任意 GC 或多 Table 模块。
• API、分包错误路径、共享 Table 转换夹具及干净安装经过本地验证；这些测试不代表任意 Unity 游戏、Windows/Linux 或真实设备已完成验收。

上游来源与修改

随包 vendor/wasm-split.js 和 vendor/wasm-split.wasm 是基于 Binaryen 132、使用 Emscripten 4.0.14 编译的修改版产物，不是原样复制的官方二进制。

本包包含以下适配：

1. Profile 哈希补丁：将上游 src/tools/wasm-split/wasm-split.cpp 的 Profile 哈希改为 signed-byte uint64 运算，以保持与原生 64 位工具的兼容性。补丁原文随包保存在 patches/portable-profile-hash.patch。
2. Node.js 封装：字节数组输入输出、临时文件管理与独立子进程执行。
3. Table ID 转换器：基于固定 Binaryen JS API 转换 placeholder 路由。

源码入口：Binaryen version_132、wasm-split、Emscripten 4.0.14。产物及许可证文件的 SHA-256 记录于 vendor/manifest.json。

许可证与第三方声明

本包包含不同许可的组件，根目录 LICENSE 的 MIT 许可仅适用于自有封装，不能据此将全部第三方代码重新声明为 MIT。

| 组件 | 许可 | 随包文件 | | --- | --- | --- | | Node.js 封装及 Table ID 适配器 | MIT | LICENSE | | Binaryen / 修改版 wasm-split | Apache-2.0 | vendor/BINARYEN-LICENSE | | Binaryen 所含 FP16 | MIT | vendor/FP16-LICENSE | | Emscripten 运行时代码 | MIT 或 University of Illinois/NCSA（上游双许可） | vendor/EMSCRIPTEN-LICENSE |

完整来源及修改声明见 THIRD_PARTY_NOTICES.md；依赖包 [email protected] 保留其自身的许可证材料。

再次分发时，请保留适用的许可证全文、版权及归属声明、修改标记，以及上游随分发提供且适用的 NOTICE 内容；继续修改时应明确标注修改。Apache-2.0 不授予上游商标或背书权利。具体权利和义务以各组件许可证原文为准。