tween.js 内存泄漏预防：怎么正确停止动画与清理对象

tween.js 发生内存泄漏的根本原因，在于未停止的动画实例或链式动画长期驻留在全局动画组中，其内部维护的数组和回调闭包对 DOM 元素、3D 网格（Mesh）或业务对象保持强引用，导致垃圾回收器（GC）无法释放对应内存。彻底预防与解决这一问题，核心路径是两点：一是放弃全局单例模式，为组件或场景分配独立的 Group 实例，在卸载时统一调用 group.removeAll()；二是在停止动画时显式调用 tween.stop() 与 tween.stopChainedTweens()，并及时取消 requestAnimationFrame 循环及断开外部引用。

一、为什么 tween.js 会引起内存泄漏：对象保留链深度拆解

在单页应用（SPA）或大型 Three.js 可视化项目中，动画往往伴随着组件的装载而创建，并在组件卸载、页面切换或数据刷新时结束。很多开发者直觉上认为：“只要从 DOM 树中移除了节点，或者组件被销毁了，附着在其上的动画和内存自然会被浏览器回收”。这种假设在 tween.js 中并不成立。

要理解泄漏的成因，必须深入 tween.js 内部的引用拓扑结构：

1. 全局单例维护的强引用数组：当通过 new TWEEN.Tween(coords).start() 启动动画时，如果不显式指定宿主组，tween.js 会默认将其推入全局共享组 TWEEN（即默认的 Group 单例）。该组在内部以私有数组（或对象字典）存储所有活跃动画。由于全局单例挂载在根作用域（GC Root）下，只要该数组中还残留有 Tween 实例，垃圾回收器就绝不会将其回收。
2. 目标对象的长期锁定（_object）：每个 Tween 实例在构造时都会接收一个目标对象（例如 mesh.position、style 对象或组件响应式数据），并将其赋给内部变量 this._object。由于 Tween 本身被全局组引用，该目标对象及其级联引用的整个大型对象（如包含数十万顶点的 Three.js 几何体、纹理贴图或复杂的 Vue/React 虚拟节点）也将被死死锁在内存中。
3. 事件回调中的闭包陷阱：在 onUpdate 或 onComplete 中，我们通常会编写箭头函数或方法调用。这些回调函数的作用域链隐式捕获了外部变量甚至整个宿主组件（如 this）。即便目标 DOM 已经被 removeChild，闭包的存在依然会让组件实例沦为“僵尸对象”，无法触发垃圾回收。
4. 未停止的帧循环（requestAnimationFrame）：如果在主循环中每帧无条件调用 TWEEN.update()，动画计算引擎便持续活跃。一旦有因为逻辑疏忽未停止的动画，它就会在后台每秒执行 60 次更新，不仅消耗 CPU 和电量，还会持续产生新的临时对象。

二、停止动画的核心机制与三大常见陷阱

在控制动画生命周期时，很多开发者仅凭记忆调用一个 tween.stop()，以为万事大吉。然而在复杂的业务交互中，这种做法极易遗留隐蔽的内存泄漏漏洞。

陷阱一：调用了 stop()，却漏掉了链式动画（chain）

tween.js 提供了极其便利的链式调度方法 tweenA.chain(tweenB, tweenC)。当 tweenA 完成后，会自动触发 tweenB 的启动。

但是，如果动画在执行过程中因为用户交互（如关闭弹窗、切换菜单）被提前中断，仅仅调用 tweenA.stop()，虽然 tweenA 停止了，但它内部的 _chainedTweens 数组依然强引用着 tweenB 和 tweenC。更糟糕的是，如果外部逻辑或者后续状态不慎激活了链条上的其他分支，这些子动画就会在看不见的地方悄然启动并长生不老。

// 错误示范：链式动画只停了首节点
tweenA.stop(); // tweenB, tweenC 依然被强引用保留在 _chainedTweens 中！

// 正确示范：递归终止整条动画链
tweenA.stop();
tweenA.stopChainedTweens(); // 显式截断所有派生链条

陷阱二：高频交互场景下不断 new Tween，旧实例未移除

例如在鼠标跟随、拖拽、窗口缩放或频繁的悬浮提示交互中，很多逻辑会在事件回调内直接创建并启动新动画：

// 危险代码：高频事件触发不断追加，旧动画在组内堆积
element.addEventListener('mousemove', (e) => {
  new TWEEN.Tween(box.position)
    .to({ x: e.clientX, y: e.clientY }, 200)
    .start();
});

在旧动画尚未执行完毕之前，新的动画已经推入数组。在快速晃动鼠标的数秒内，动画数组的长度可能迅速飙升至数百个，多个动画同时操纵同一个对象的属性，造成计算冲突、画面掉帧以及瞬间的内存暴增。正确的做法是：在启动新动画前，务必先停止并清理上一个动画的引用。

陷阱三：动画执行结束与对象被清理并非同一概念

虽然 tween.js 在动画自然运行至 duration 结束（触发 onComplete）后，会自动从所在的组数组中移除自身，但如果在组件卸载时动画尚未结束，或者动画设置了 repeat(Infinity)，它就永远不会自然退出。因此，生命周期清理必须是主动防御式的，而不能寄希望于“等它自己播完”。

三、停止与彻底清理对象的标准四步法（SOP）

为了确保在任何异常、提前关闭或组件销毁场景下都不出现内存滞留，推荐遵循以下标准的四步清理流程：

步骤一：主动中断当前动画与链式派生

不论动画当前处于播放中、延迟等待（delay）还是重复循环（repeat）状态，均应立即调用 stop()，并紧跟 stopChainedTweens()：

if (currentTween) {
  currentTween.stop();
  currentTween.stopChainedTweens();
}

步骤二：从管理组中注销实例

尽管 stop() 内部会尝试将自身从组中剥离，但在多分支或批量控制场景下，直接通过宿主组执行精准注销是更为稳健的做法。如果是批量卸载，推荐直接清空：

// 单个移除
myGroup.remove(currentTween);

// 或者在组件销毁时全量清空
myGroup.removeAll();

步骤三：暂停或解除 requestAnimationFrame 驱动循环

帧循环是维持引擎运转的心跳。如果页面已经没有需要执行的动画（或者当前组件的独立组已清空），应当及时通过句柄取消 requestAnimationFrame，避免空转：

if (animationFrameId !== null) {
  cancelAnimationFrame(animationFrameId);
  animationFrameId = null;
}

步骤四：解除外部强引用与清除闭包

最后一步是很多团队容易遗漏的关键点：在 JavaScript 运行环境中，只要你的类属性、全局变量或闭包仍然指向 currentTween 或动画目标对象，该对象依然具有到达根节点的路径。必须将其显式赋空：

// 切断外部引用，让垃圾回收器可以在下一周期无障碍收回
currentTween = null;
targetObject = null;

四、架构级预防：使用独立 Group 取代全局 TWEEN 单例

在过去的初学者教程中，官方简写常引导大家直接使用全局 TWEEN 对象。但在现代工程化前端体系（Vue、React、Svelte 或大型 Three.js 场景）中，使用全局单例是导致内存泄漏和状态混乱的最大元凶。

如上图所示，当多个组件共同向全局 TWEEN 注册动画时：

• 你无法安全地调用 TWEEN.removeAll()，因为清空全局数组会连带摧毁其他正在正常播放动画的组件；
• 某一个组件因为编写疏忽忘记清理单个 Tween，就会使该组件内部的所有闭包长期悬挂在全局单例下；
• 多个模块共享同一个 TWEEN.update() 驱动源，排查时无法区分哪一段 CPU 占用是由哪个业务模块产生的。

标准重构：采用独立 Group 实例并绑定组件生命周期

最佳的架构实践是：为每个具有独立生命周期的模块、页面或组件，实例化独立的 new TWEEN.Group()。组件的装载即 Group 的创建，组件的卸载即 Group 的全量销毁。

以下分别给出 React 与 Vue 3 下严谨、无泄漏的标准编写模式：

1. React (Hooks) 完整防护实践

import React, { useEffect, useRef } from 'react';
import * as TWEEN from '@tweenjs/tween.js';

export const AnimatedBox = () => {
  const boxRef = useRef(null);

  useEffect(() => {
    // 1. 为当前组件实例分配专有的动画组
    const group = new TWEEN.Group();
    let rafId = null;

    const coords = { x: 0, opacity: 0 };
    const tween = new TWEEN.Tween(coords, group)
      .to({ x: 100, opacity: 1 }, 1000)
      .easing(TWEEN.Easing.Quadratic.Out)
      .onUpdate(() => {
        if (boxRef.current) {
          boxRef.current.style.transform = `translateX(${coords.x}px)`;
          boxRef.current.style.opacity = coords.opacity;
        }
      })
      .start();

    // 2. 独立受控的驱动帧循环
    const animate = (time) => {
      const hasRemaining = group.update(time);
      if (hasRemaining) {
        rafId = requestAnimationFrame(animate);
      } else {
        rafId = null;
      }
    };
    rafId = requestAnimationFrame(animate);

    // 3. 在卸载清理函数中统一销毁
    return () => {
      if (rafId !== null) {
        cancelAnimationFrame(rafId);
      }
      tween.stop();
      tween.stopChainedTweens();
      group.removeAll(); // 一键清空组内所有残留
    };
  }, []);

  return <div ref={boxRef} className="box">内容</div>;
};

2. Vue 3 (Composition API) 完整防护实践

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import * as TWEEN from '@tweenjs/tween.js';

const boxEl = ref(null);
let group = null;
let activeTween = null;
let rafHandle = null;

onMounted(() => {
  group = new TWEEN.Group();
  const state = { scale: 1 };

  activeTween = new TWEEN.Tween(state, group)
    .to({ scale: 1.5 }, 800)
    .repeat(Infinity)
    .yoyo(true)
    .onUpdate(() => {
      if (boxEl.value) {
        boxEl.value.style.transform = `scale(${state.scale})`;
      }
    })
    .start();

  const tick = (time) => {
    group.update(time);
    rafHandle = requestAnimationFrame(tick);
  };
  rafHandle = requestAnimationFrame(tick);
});

onBeforeUnmount(() => {
  // 组件即将卸载时严格执行防泄漏清理
  if (rafHandle) {
    cancelAnimationFrame(rafHandle);
    rafHandle = null;
  }
  if (activeTween) {
    activeTween.stop();
    activeTween.stopChainedTweens();
    activeTween = null;
  }
  if (group) {
    group.removeAll();
    group = null;
  }
});
</script>

五、内存泄漏的实测排查：使用 Chrome DevTools 验证

无论是重构老旧代码还是验证新方案的安全性，都不能只停留在代码层面，必须通过浏览器的内存分析工具（Memory Profiler）给出确切证据。

1. 堆快照（Heap Snapshot）对比操作步骤

1. 打开待测试页面，按 F12 打开 Chrome DevTools，切换至 Memory 面板；
2. 选择 Heap snapshot，在页面初始状态下点击 Take snapshot，记录为 Snapshot 1；
3. 在页面中触发创建动画的操作（如打开一个包含动画的弹窗或加载一个带有 3D 模型的子路由），等待动画运行；
4. 关闭该弹窗或离开该子路由（触发卸载流程），手动点击 DevTools 左上角的垃圾桶图标（Collect garbage），强制触发一次全量垃圾回收；
5. 拍摄 Snapshot 2；
6. 重复上述“打开 - 关闭”操作 5 到 10 次，拍摄 Snapshot 3。

2. 关键定位指标与 Retainers 检查

在 Snapshot 3 的 Class filter 过滤框中依次搜索以下关键构造函数：

• Tween / Group：在组件全部关闭的状态下，其 # Alloc.（分配数）与 # Freed（释放数）应当持平，活动实例计数（# Delta）必须为 0。如果依然存在非零对象，展开该行。
• 查看下方 Retainers（保留树）：选中残留的 Tween 实例，查看底部的引用关系。若能看到 _tweens in Group 或 window.TWEEN，说明卸载时未执行 stop() 或 removeAll()；若能看到 context in closure，说明回调中的外部变量仍被持有。
• Detached HTMLElement：若页面包含 DOM 动画，搜索 Detached。如果发现数量随着弹窗开关不断线性累加，点击该节点即可在 Retainer 中明确看到其正被某一个未停止的 Tween._object 引用。

六、核心防泄漏规范与全景自查清单

为了在团队开发中建立长效的质量防线，下表总结了 tween.js 核心生命周期 API 的用途、触发时机以及风险规避点：

总结而言，tween.js 本身是一个精巧而轻量的高性能补间动画库，它本身并不存在设计上的内存缺陷；真正的内存泄漏绝大多数源于“将局部生命周期的动画托付给了全局生命周期的单例”，以及“在非正常结束时遗漏了派生链与帧循环的切断”。只要在工程中坚持独立 Group 隔离，并在销毁钩子中严格践行停止链条、注销实例、切断循环、释放引用的四步闭环，就能彻底规避内存泄漏隐患，保持应用长时间平稳丝滑地运行。