ammo.js 内存管理：避免 Wasm 环境下的内存泄漏技巧

一、双运行时机制：为什么 JS 垃圾回收无法清理 Wasm 内存？

在标准的 JavaScript 开发中，当一个对象不再具有任何引用时，垃圾回收器（GC）会在下一个清理周期自动回收其占用的内存空间。然而，ammo.js 并不是纯 JavaScript 实现，而是借助 Emscripten 通过 WebIDL Binder 将 C++ 代码编译成 WebAssembly 模块运行的。这就形成了两个截然不同的内存领域：JavaScript 虚拟机的受控托管堆，以及 WebAssembly 运行时的平坦线性内存堆（即 Ammo.HEAP8 或 Ammo.HEAPF32 对应的底层 ArrayBuffer）。

当执行 const vec = new Ammo.btVector3(0, 10, 0); 时，底层实际上发生了两件事：

1. C++ 堆分配：WebAssembly 模块调用底层内存分配器（如 malloc），在线性内存堆中分配出存放 btVector3 三维浮点结构体所需的固定字节，并返回该内存段的起始数字指针（例如 0x00A180）。
2. JS 包装壳构建：V8 等 JS 引擎在 JS 托管堆中创建一个极小的代理包装对象（Wrapper Object）。该对象内部仅持有一个指向该地址的整型数值字段 ptr。

如果开发者在后续逻辑中简单地执行 vec = null;，或者该变量随函数执行完毕退出了作用域，JavaScript 垃圾回收器确实会回收那个仅仅几十字节大小的 JS 包装对象。但是，垃圾回收器无法感知也无法跨界清理 WebAssembly 线性堆中的内存。在 Wasm 运行时看来，位于 0x00A180 处的物理结构从未收到释放指令，它将作为一块孤儿内存（Orphaned Memory）永久滞留在堆中。

当这类孤儿内存不断积累，WebAssembly 的初始内存池被耗尽，运行时就会被迫调用 WebAssembly.Memory.prototype.grow() 向宿主环境申请扩容。这一底层系统调用会重新分配更大的 ArrayBuffer 并将旧内存逐字节拷贝至新空间，直接导致主线程出现剧烈掉帧；而当总内存触及浏览器或操作系统的分配上限后，程序就会直接报错抛出 RangeError: WebAssembly.Memory.grow() failed 并使页面崩溃。

二、核心规则：Ammo.destroy 的生命周期与安全析构顺序

要回收 WebAssembly 线性堆中的内存，必须显式调用 ammo.js 暴露的销毁方法：Ammo.destroy(instance)。其本质是调用 C++ 侧的 delete 析构运算符，通知物理引擎底层分配器将对应地址标记为空闲。

Bullet 物理引擎内部存在严密的树状指针依赖关系。物理世界引用刚体，刚体引用运动状态（MotionState）和碰撞几何体（CollisionShape），而物理世界本身又严重依赖约束求解器、碰撞分发器和宽相检测器。如果颠倒销毁顺序（例如先销毁了 CollisionShape 却未先移除引用它的刚体），底层碰撞检测管线就会访问到悬垂指针（Dangling Pointer）。

在销毁一个场景或重置物理模拟时，必须遵循严格自顶向下的逆序析构流程：

安全销毁的十个具体步骤：

1. 解绑物理约束与动作：调用 dynamicsWorld.removeConstraint(constraint)，解除刚体间的连接关系。
2. 解绑刚体对象：遍历场景中的所有刚体，调用 dynamicsWorld.removeRigidBody(body) 将其从模拟管线中移出。
3. 销毁刚体实例：调用 Ammo.destroy(body) 回收刚体底层实体。
4. 销毁运动状态：调用 Ammo.destroy(body.getMotionState())。注意：销毁刚体并不会级联销毁绑定的 btDefaultMotionState，必须单独释放。
5. 销毁碰撞几何体：调用 Ammo.destroy(shape)。如果是复合形状 btCompoundShape，必须先递归遍历并销毁所有子形状（Child Shapes）；如果是多个刚体共享同一个几何体，只应在最后一个使用者卸载时销毁一次。
6. 校验世界对象清空：调用 dynamicsWorld.getNumCollisionObjects() === 0，确认物理管线内再无残留对象。
7. 销毁离散动态世界：调用 Ammo.destroy(dynamicsWorld)，释放物理世界核心调度器。
8. 销毁约束求解器：调用 Ammo.destroy(solver)，释放冲量计算矩阵与内部内存池。
9. 销毁宽相检测与分发器：依次调用 Ammo.destroy(broadphase) 和 Ammo.destroy(dispatcher)。
10. 销毁碰撞配置基底：调用 Ammo.destroy(collisionConfiguration)，最后清空辅助池对象并将变量设为 null。

三、高频每帧循环的内存重灾区与对象池复用技巧

在实际项目中，超过 80% 的 ammo.js 内存泄漏并非发生在场景切换时，而是隐藏在 requestAnimationFrame 驱动的每帧渲染循环中。

典型的错误做法是在每一帧为了将刚体的位置和旋转同步到 Three.js 或 Babylon.js 网格，在循环内部频繁通过 new Ammo.btTransform() 或 new Ammo.btVector3() 获取数据。即使每一帧循环末尾变量自动离开了作用域，由于 Wasm 内存无法被垃圾回收，60 FPS 下一个包含 100 个物理实体的场景每秒将产生 6,000 次堆分配，仅仅运行数分钟就会吃掉数百兆内存。

技巧一：使用静态 Scratchpad 临时对象池

对于高频调用的物理同步与坐标转换，应该在物理更新逻辑之外预先分配一组专用的辅助对象，在循环体中反复向同一个内存空间写入数据，实现帧循环内的“零堆分配”（Zero Allocation）。

// ==========================================
// 物理同步管理器：基于静态 Scratchpad 的无泄漏实现
// ==========================================
export class PhysicsSyncManager {
  constructor(physicsWorld) {
    this.world = physicsWorld;
    this.bindings = []; // 存放 { mesh, body } 配对

    // 预先分配静态复用对象（Scratchpad 单例）
    // 全生命周期内仅分配一次，严禁在 tick 内重复 new
    this._tempTransform = new Ammo.btTransform();
  }

  // 每帧渲染循环调用的同步函数
  update() {
    const list = this.bindings;
    const trans = this._tempTransform;

    for (let i = 0; i < list.length; i++) {
      const { mesh, body } = list[i];
      const motionState = body.getMotionState();

      if (motionState) {
        // 将世界变换直接写入预分配的 _tempTransform 地址中
        motionState.getWorldTransform(trans);

        const origin = trans.getOrigin();
        const rotation = trans.getRotation();

        // 同步至三维网格（Three.js 坐标）
        mesh.position.set(origin.x(), origin.y(), origin.z());
        mesh.quaternion.set(rotation.x(), rotation.y(), rotation.z(), rotation.w());
      }
    }
  }

  // 管理器销毁时，切记释放预分配的临时单例
  dispose() {
    if (this._tempTransform) {
      Ammo.destroy(this._tempTransform);
      this._tempTransform = null;
    }
    this.bindings.length = 0;
    this.world = null;
  }
}

技巧二：射线检测与回调结果对象的复用

除了刚体同步外，高频的射线检测（Raycast，如角色脚底贴地检测、射击瞄准）也是重灾区。每次执行射线投射时使用的 Ammo.ClosestRayResultCallback，内部同样分配了 C++ 结构。

如果在循环中每次都 new Ammo.ClosestRayResultCallback(from, to)，不仅会分配结果回调对象，还会产生额外的内存碎屑。正确的做法是：

• 在初始化阶段预先创建好固定的 rayCallback 单例。
• 在执行新的检测前，通过其成员函数重置射线起止坐标（或调用相应的更新函数）。
• 当不再需要射线模块时，显式调用 Ammo.destroy(rayCallback) 释放。

四、工程化排查与内存泄漏监控手段

在实际项目开发中，依靠人工审查代码难以百分之百避免疏漏。建立量化监控与拦截排查机制，是确保物理模块长期平稳运行的关键。

手段一：监控 WebAssembly 线性堆字节尺寸

通过检测 ammo.js 暴露给全局的 TypedArray 视图缓冲区长度，可以以极轻量的开销实时掌握内存走向：

// 打印当前 Ammo Wasm 线性堆的实际字节大小
function getAmmoHeapByteSize() {
  return Ammo.HEAP8.buffer.byteLength;
}

// 格式化输出兆字节 (MB)
function logAmmoMemory(label = "Status") {
  const mb = (Ammo.HEAP8.buffer.byteLength / (1024 * 1024)).toFixed(2);
  console.log(`[Ammo Memory] ${label}: ${mb} MB`);
}

判断标准：在一个设计良好的物理系统中，当场景所有刚体和碰撞体初始化完成后，Ammo.HEAP8.buffer.byteLength 应该在后续运行过程中呈现一条完全水平的直线。如果在空闲运行或场景来回切换时，该数值不断出现阶梯式翻倍跃升，即可 100% 确认存在 Wasm 堆泄漏。

手段二：开发环境 Allocation Tracker（代理跟踪器）

为了精确揪出到底漏销毁了哪一种类型的对象，可以在测试阶段通过 JavaScript 的 Proxy 或函数劫持，在 Ammo 命名空间中对构造函数和 destroy 进行包装记录：

// ==========================================
// 仅在开发环境启用的内存分配拦截跟踪器
// ==========================================
export class AmmoLeakTracker {
  static activePointers = new Map(); // ptr -> { className, stack }
  static originalDestroy = Ammo.destroy;

  static enable(trackedClasses = ['btRigidBody', 'btBoxShape', 'btTransform']) {
    // 劫持构造函数
    trackedClasses.forEach(className => {
      const OrigClass = Ammo[className];
      if (!OrigClass) return;

      Ammo[className] = function (...args) {
        const instance = new OrigClass(...args);
        const ptr = Ammo.getPointer ? Ammo.getPointer(instance) : instance.ptr;
        
        AmmoLeakTracker.activePointers.set(ptr, {
          className,
          createdAt: Date.now(),
        });
        return instance;
      };
      Ammo[className].prototype = OrigClass.prototype;
    });

    // 劫持 destroy
    Ammo.destroy = function (obj) {
      if (obj) {
        const ptr = Ammo.getPointer ? Ammo.getPointer(obj) : obj.ptr;
        AmmoLeakTracker.activePointers.delete(ptr);
      }
      return AmmoLeakTracker.originalDestroy.call(Ammo, obj);
    };
  }

  // 场景切换后检查残留未释放指针
  static reportLeaks() {
    console.warn(`[Ammo Tracker] 当前未销毁活跃实体总数: ${this.activePointers.size}`);
    const counts = {};
    this.activePointers.forEach(item => {
      counts[item.className] = (counts[item.className] || 0) + 1;
    });
    console.table(counts);
  }
}

五、Ammo.js 内存治理全景矩阵

综合上述各个环节的技术要点，避免 Wasm 环境下的内存泄漏需要贯穿整个工程周期的协同规范。

核心排查与操作规程速查表

在 WebAssembly 与 JavaScript 混合运行的架构中，自动垃圾回收与手动内存管理同时存在。理解两个世界的边界，坚持“谁分配谁负责显式销毁”的原则，在高频计算中坚决采用静态对象池复用，并在析构时遵守严格的逆序规范，即可彻底根治 ammo.js 在 Web 端运行时的内存泄漏顽疾，确保复杂 3D 物理交互应用的长效稳定。