怎么编译裁剪版 ammo.js 以减小 Wasm 体积？

一、为什么官方 ammo.js 的体积如此庞大？

在 WebGL 和 Web 3D 领域，ammo.js 是最经典的物理解决方案之一，广泛应用于 Three.js、Babylon.js 以及众多自研引擎中。理解它的体积问题，首先需要了解其底层架构。

ammo.js 本质上并非用 JavaScript 或 Rust 原生重写的物理引擎，而是通过 Emscripten 交叉编译工具链将开源工业级 C++ 物理引擎 Bullet Physics 直接编译为 WebAssembly，并借助 WebIDL Binder 自动生成外部 JS 交互胶水层。

Bullet Physics 作为一个经历了二十余年工业验证的完备系统，内部划分了大量的复杂子模块：

• 软体动力学系统（BulletSoftBody）：涵盖布料模拟、绳索刚度计算、可变形四面体体积网格和气囊模拟。
• 车辆动力学系统（BulletDynamics/Vehicle）：包含光线投射轮轴、悬挂计算器与摩擦反馈。
• 复杂网格算法（BulletCollision/GImpact & HACD）：处理任意凹面网格碰撞的三角剖分与凸分解。
• 多自由度约束求解器：通用 6DoF 弹簧、锥形扭转、齿轮、滑块与万向节。

官方在发布预编译版本时，出于“最大兼容度”和“开箱即用”的考虑，在 ammo.idl 接口定义文件中将 Bullet 的上述所有子系统全部暴露给了外部。在 C++ 编译器和链接器眼中，只要胶水层对这些类有导出引用，其虚函数表、复杂数学模板类与关联方法就全部属于“活跃符号”。因此，即使你的 3D 场景只创建了一个下落的木箱，浏览器也必须加载整套体积超过 2MB 的全功能 Wasm 模块。

二、核心机制：WebIDL Binder 与死代码消除（LTO）

裁剪 ammo.js 不需要开发者深入修改 Bullet 底层成百上千个 C++ 源文件。它的模块裁剪逻辑是自上而下自动触发的，核心依赖于 WebIDL Binder 胶水生成机制与 LLVM 链接期优化（Link-Time Optimization, LTO） 的联动。

在整个编译管线中，ammo.idl 充当了暴露到 JavaScript 环境的唯一接口白名单。整个死代码剔除过程包含三个关键步骤：

1. 接口声明裁切：当我们在 ammo.idl 中删去或注释掉 interface btSoftBody 及其衍生类时，接口白名单中便不再包含软体模块。
2. 胶水层解耦：Python 构建脚本驱动 webidl_binder.py 解析 IDL，自动生成中间文件 glue.cpp 与 glue.js。因为 IDL 中没有软体声明，生成的 glue.cpp 中将完全没有任何指向 btSoftBody 的实例化代码与调用网关（Call Sites）。
3. LLVM LTO 触发全量死代码剥离：在随后的编译阶段，Emscripten 的 Clang 编译器加载 Bullet 的所有源文件。虽然 C++ 源码依然在目录中，但在开启 -flto 优化标志后，链接器会在全项目维度构建符号引用图谱。链接器发现 btSoftBody.cpp 等文件中的虚函数表和实现逻辑没有任何调用入口，将其标记为“Dead Code”并整体裁剪剔除。

三、实操步骤一：编译环境搭建与依赖准备

编译裁剪版 ammo.js 建议在 Linux、macOS 或 Windows WSL 环境下进行。确保系统已安装 Python 3、Git 以及 CMake。

1. 安装并激活 Emscripten SDK（emsdk）

ammo.js 的编译构建对 Emscripten 的版本稳定性有一定要求。尽管最新版本通常可用，但不同大版本间 webidl_binder.py 的生成规则偶有变动。推荐使用经过充分验证的稳定版本，例如 3.1.45。

在终端中执行以下命令拉取并配置 emsdk：

# 1. 克隆官方 emsdk 仓库
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk

# 2. 安装并激活指定稳定版本
./emsdk install 3.1.45
./emsdk activate 3.1.45

# 3. 将编译器路径载入当前 Shell 会话环境变量
source ./emsdk_env.sh

检查编译器是否就绪：

emcc -v

2. 克隆 ammo.js 源码仓库

保持在同一个已加载 emsdk_env.sh 的终端窗口中，克隆 ammo.js 仓库并拉取 Bullet C++ 子模块：

# 克隆 ammo.js 源码
git clone https://github.com/kripken/ammo.js.git
cd ammo.js

# 初始化并更新 Bullet C++ 子模块依赖
git submodule update --init --recursive

四、实操步骤二：精准裁剪 ammo.idl 接口定义

根目录下的 ammo.idl 是本操作最关键的文件。用文本编辑器打开它，可以看到数千行的接口定义。接下来针对常见 3D 刚体项目执行模块级裁剪。

1. 彻底删除软体动力学系统（立减约 920KB）

软体动力学（SoftBody）是体积膨胀的首要元凶，占了总体积的 40% 以上。如果项目仅涉及刚体撞击、重力掉落或射线拾取，直接搜索并删除所有与 btSoftBody 相关的接口声明。

需要删除或注释的典型接口列表包括：

• interface btSoftBodyWorldInfo
• interface btSoftBody : btCollisionObject
• interface btSoftRigidDynamicsWorld : btDiscreteDynamicsWorld
• interface btSoftBodyRigidBodyCollisionConfiguration : btDefaultCollisionConfiguration
• interface btSoftBodySolver 与 btDefaultSoftBodySolver
• interface btSoftBodyHelpers 及所有涉及绳索、布料初始化的辅助函数

2. 剔除射线车辆动力学（节约约 340KB）

除非正在制作包含悬挂物理、车轮摩擦的赛车模拟类游戏，否则应当剔除车辆子模块：

• interface btRaycastVehicle
• interface btVehicleRaycaster 与 btDefaultVehicleRaycaster
• interface btWheelInfo 与 btVehicleTuning

3. 裁剪非必要几何形状与凸分解（节约约 200KB）

Bullet 提供了数十种碰撞几何体。对于标准 3D 应用，应当建立清晰的保留与剔除边界：

4. 裁剪多余的高级约束求解器

仅保留点对点约束 btPoint2PointConstraint、铰链约束 btHingeConstraint 或常用的定轴约束。移除 btGearConstraint（齿轮）、btSliderConstraint（滑块）、btConeTwistConstraint（锥形扭转）等冷门约束。

5. ammo.idl 裁剪示例（Git Diff 样式）

--- a/ammo.idl
+++ b/ammo.idl
@@ -120,38 +120,6 @@ interface btDefaultCollisionConfiguration : btCollisionConfiguration {
   void btDefaultCollisionConfiguration();
 };
 
-// =================== 裁剪移除全套软体配置 ===================
-[Prefix="btSoftBody::"]
-interface Config {
-  attribute float kVCF;
-  attribute float kDP;
-  attribute float kDG;
-};
-
-interface btSoftBodyWorldInfo {
-  void btSoftBodyWorldInfo();
-  attribute float m_gravity;
-};
-
-interface btSoftRigidDynamicsWorld : btDiscreteDynamicsWorld {
-  void btSoftRigidDynamicsWorld(btDispatcher dispatcher, btBroadphaseInterface pairCache, btConstraintSolver constraintSolver, btCollisionConfiguration collisionConfiguration, btSoftBodySolver softBodySolver);
-  void addSoftBody(btSoftBody body, short collisionFilterGroup, short collisionFilterMask);
-};
-
-// =================== 裁剪移除车辆系统 ===================
-interface btRaycastVehicle {
-  void btRaycastVehicle(btVehicleTuning tuning, btRigidBody chassis, btVehicleRaycaster raycaster);
-  void addWheel(btVector3 connectionPointCS0, btVector3 wheelDirectionCS0, btVector3 wheelAxleCS, float suspensionRestLength, float wheelRadius, btVehicleTuning tuning, boolean isFrontWheel);
-};

五、实操步骤三：调优 make.py 编译配置与链接参数

make.py 是 ammo.js 官方的构建脚本。为了让裁剪效果发挥到极致，我们需要对其编译与链接标志（Flags）进行针对性调整。

关键配置项与优化标志解析

• -Oz 替换默认的 -O3：-O3 追求极致运行速度，往往会进行大量的内联展开和循环展开，导致代码体积增大；而 -Oz 指示 Clang 以“最小化输出体积”为最高优先级进行代码优化。
• 注入 -flto（Link-Time Optimization）：这是让死代码剔除生效的核心引擎。开启 LTO 后，编译器会在链接所有 .o 目标文件时跨翻译单元执行全局死代码消除。
• 内存模型配置：添加 -s ALLOW_MEMORY_GROWTH=1，并将初始堆内存 INITIAL_MEMORY 调整为 32MB（33554432）。这避免了预分配过大固定内存块，使得模块运行时占用更贴合实际业务。
• 运行时轻量化：添加 -s NO_FILESYSTEM=1 禁用不需要的虚拟文件系统，设置 -s ENVIRONMENT="web,worker" 剔除 Node.js 兼容层以压缩胶水代码。
• Closure Compiler：在生产构建中开启 --closure 1，将生成的 ammo.js 胶水代码深度混淆压缩。

打开 make.py，定位到构建编译配置部分进行修改：

# make.py 关键修改片段
emcc_args = [
    '-Oz',                         # 核心优化等级：体积优先
    '-flto',                       # 开启链接期全程序优化（死代码消除）
    '--llvm-lto', '1',
    '-s', 'WASM=1',                # 生成 WebAssembly 目标
    '-s', 'ALLOW_MEMORY_GROWTH=1', # 允许内存动态扩容
    '-s', 'INITIAL_MEMORY=33554432',# 初始内存设置为 32MB
    '-s', 'NO_FILESYSTEM=1',       # 物理计算无需 Emscripten 虚拟文件系统
    '-s', 'ENVIRONMENT="web,worker"',
    '-s', 'EXPORTED_RUNTIME_METHODS=["UTF8ToString"]',
    '-s', 'MODULARIZE=1',          # 导出为 UMD / Promise 风格模块
    '-s', 'EXPORT_NAME="Ammo"',
    '-s', 'ASSERTIONS=0',          # 关闭调试断言以减小体积
    '--closure', '1'               # 开启 Closure 压缩 JavaScript 胶水层
]

六、实操步骤四：执行构建、体积对比与功能验证

配置完成后，在 ammo.js 仓库根目录下执行构建命令。构建脚本会自动调用 Python 绑定器生成 glue.cpp 与 glue.js，随后启动 emcc 进行编译。

# 执行构建命令（生成 WebAssembly 版本）
python3 make.py wasm

产物体积衰减实测对比

编译完成后，进入 builds/ 目录观察产物体积变化：

ls -lh builds/ammo.*

下表记录了不同裁剪策略在真实构建下的二进制文件体积对比：

轻量化产物运行时功能验证

为了确认裁剪后的 Wasm 模块功能正常且没有破坏刚体物理模拟，编写一段标准的物理测试用例（可在 Node.js 或浏览器控制台中运行）：

// verify-ammo.js: 验证裁剪版 ammo.wasm 核心刚体仿真能力
import Ammo from './builds/ammo.js';

async function runPhysicsTest() {
  const ammoInstance = await Ammo();
  console.log('✔ Ammo.js 模块初始化成功');

  // 1. 初始化核心碰撞配置与派发器
  const collisionConfiguration = new ammoInstance.btDefaultCollisionConfiguration();
  const dispatcher = new ammoInstance.btCollisionDispatcher(collisionConfiguration);
  const overlappingPairCache = new ammoInstance.btDbvtBroadphase();
  const solver = new ammoInstance.btSequentialImpulseConstraintSolver();

  // 2. 创建离散动力学刚体世界
  const dynamicsWorld = new ammoInstance.btDiscreteDynamicsWorld(
    dispatcher,
    overlappingPairCache,
    solver,
    collisionConfiguration
  );
  dynamicsWorld.setGravity(new ammoInstance.btVector3(0, -9.8, 0));

  // 3. 创建静态地面（Static Plane）
  const groundShape = new ammoInstance.btStaticPlaneShape(new ammoInstance.btVector3(0, 1, 0), 0);
  const groundTransform = new ammoInstance.btTransform();
  groundTransform.setIdentity();
  groundTransform.setOrigin(new ammoInstance.btVector3(0, 0, 0));
  const groundMotionState = new ammoInstance.btDefaultMotionState(groundTransform);
  const groundRigidBodyCI = new ammoInstance.btRigidBodyConstructionInfo(0, groundMotionState, groundShape);
  const groundBody = new ammoInstance.btRigidBody(groundRigidBodyCI);
  dynamicsWorld.addRigidBody(groundBody);

  // 4. 创建一个位于 Y=10 的自由落体小球
  const sphereShape = new ammoInstance.btSphereShape(1.0);
  const sphereTransform = new ammoInstance.btTransform();
  sphereTransform.setIdentity();
  sphereTransform.setOrigin(new ammoInstance.btVector3(0, 10, 0));
  const sphereMotionState = new ammoInstance.btDefaultMotionState(sphereTransform);
  
  const localInertia = new ammoInstance.btVector3(0, 0, 0);
  sphereShape.calculateLocalInertia(1.0, localInertia);
  const sphereCI = new ammoInstance.btRigidBodyConstructionInfo(1.0, sphereMotionState, sphereShape, localInertia);
  const sphereBody = new ammoInstance.btRigidBody(sphereCI);
  dynamicsWorld.addRigidBody(sphereBody);

  // 5. 步进模拟 10 帧并检测 Y 坐标变化
  console.log('开始物理步进仿真：');
  const trans = new ammoInstance.btTransform();
  for (let i = 0; i < 10; i++) {
    dynamicsWorld.stepSimulation(1 / 60, 10);
    sphereBody.getMotionState().getWorldTransform(trans);
    const posY = trans.getOrigin().y().toFixed(4);
    console.log(`第 ${i + 1} 帧: 球体 Y 坐标 = ${posY} m`);
  }

  // 6. 清理内存指针
  ammoInstance.destroy(sphereBody);
  ammoInstance.destroy(sphereShape);
  ammoInstance.destroy(groundBody);
  ammoInstance.destroy(groundShape);
  ammoInstance.destroy(dynamicsWorld);
  console.log('✔ 测试完成，C++ 内存回收正常');
}

runPhysicsTest();

七、三维引擎（Three.js / Babylon.js）集成避坑与排错

将裁剪版 ammo.js 引入项目时，由于上层引擎或第三方库可能存在硬编码探测逻辑，容易遇到运行时异常。遵循下述排查决策树可快速定位问题。

1. 报错 Ammo.btSoftBodyWorldInfo is not a constructor

发生场景：使用 Three.js 官方示例提供的 AmmoPhysics.js 插件，或引入了旧版封装库时。

原因分析：部分引擎插件在初始化时，不论场景中是否使用软体，都会尝试探测 Ammo.btSoftBodyWorldInfo 或 Ammo.btSoftRigidDynamicsWorld 是否存在。如果直接删除了对应 IDL 声明，插件会抛出未定义异常。

解决方案（免改 C++ 的桩对象注入）：无需把软体 C++ 库重新编译回来，只需在 JavaScript 胶水层加载完成后，向 Ammo 实例上挂载一个轻量虚拟空对象（Stub）：

// 运行时兼容补丁：提供空桩防止三方库强行探测报错
Ammo().then(ammo => {
  if (!ammo.btSoftBodyWorldInfo) {
    ammo.btSoftBodyWorldInfo = class {};
  }
  if (!ammo.btSoftBodyHelpers) {
    ammo.btSoftBodyHelpers = class {};
  }
  // 正常初始化 Three.js AmmoPhysics
  initThreePhysics(ammo);
});

2. 地形穿透与三角网格（TriangleMesh）丢失

发生场景：游戏场景中导入的 .glb / .gltf 静态地形或楼宇模型，角色走上去直接穿透坠入虚空。

原因分析：开发者在裁剪 IDL 时过度激进，误将 btBvhTriangleMeshShape 以及 btTriangleMesh、addTriangle 一并移除了。基础刚体引擎无法为不规则三角网格生成静态碰撞体。

解决方案：对于含复杂地形的项目，必须在 ammo.idl 中保留 btBvhTriangleMeshShape、btTriangleMesh、btVector3 相关方法。

3. WebAssembly 堆内存泄露与显式回收

Bullet 运行在由 Emscripten 划分的 WebAssembly 线性内存堆（Linear Memory）中。JavaScript 的垃圾回收器（GC）无法感知 C++ 对象的生命周期。

当场景中的刚体被销毁或关卡重新加载时，必须显式调用 Ammo.destroy(ptr) 释放内部对象。如果长期忽略此操作，即便 Wasm 二进制体积再小，应用运行几分钟后也会因线性内存无限制增长（OOM）而崩溃。

八、总结与选型决策指南

通过裁剪 ammo.idl 并启用 Emscripten 链接期死代码消除（LTO），我们能够以极低的工程成本将官方庞大的 ammo.wasm 压缩到原来的 18%~30%。这彻底打破了“ ammo.js 太重、无法用于轻量 Web 应用”的刻板印象。

为了帮助你在实际项目中做出最佳选型决策，以下是推荐的梯度方案：

• 极简基元碰撞版（~380 KB）：适用于 UI 碰撞微交互、简单 3D 物品掉落、无地形或仅有平板地面的休闲小游戏。
• 标准 3D 刚体版（~680 KB）：适用于 90% 以上的标准 3D 应用，包括第一人称漫游、展厅碰撞、静态三角网格地形交互、射线拾取及门窗旋转铰链。
• 官方全量版（~2,240 KB）：仅在确需布料飘动、绳索摇摆或车辆动力学特化算法的场景下使用。

在生产环境发布时，推荐配合服务端（Nginx / CDN）开启 Brotli 预压缩（.wasm.br）。680KB 的标准刚体版本经过 Brotli 压缩后仅有 126 KB，在 4G/5G 网络下即可实现毫秒级瞬间传输与即时解析，为终端用户带来丝滑无白屏的 3D 体验。