排查 motion-anything 的动效运行时错误，需要先固定错误现象，再沿动效链路做区间切分。不要拿到报错就修改参数或替换写法，那样容易放大排查范围。第一步是把现象归入硬错误、表现异常或偶发异常中的一类，第二步才进入代码层定位。

动效运行时报错通常沿“触发条件 → 初始化 → 执行 → 回收”链路发生，应先固定错误类型，再按链路逐段验证。多数问题来自数据格式与动效参数不匹配、依赖资源尚未就绪、或生命周期节点被提前调用。排查时不要先改代码，先确认哪一段链路最早出现异常。

先固定错误现象，再进入代码层

控制台报错中断后续逻辑，是硬错误；动效不启动、中途停止、位置跳变，是表现异常；时好时坏、只在特定窗口或系统状态下复现，是偶发异常。三类现象的处理方式不同。硬错误直接读取调用栈尾部，判断异常是来自 motion-anything 内部还是业务代码传入的数据；表现异常需要把入参和逐帧数值打印出来做对比；偶发异常则需要先确认复现条件，再考虑环境变量。

按四个阶段切分动效运行链路

一次动效运行可以拆成触发、初始化、执行、回收四个阶段。触发阶段确认事件或状态真的发生，在入口处打印日志；初始化阶段检查参数解析、目标元素是否存在于文档、动画实例是否创建成功；执行阶段核对逐帧计算出的属性值；回收阶段确认动画结束后的清理动作是否执行。四个阶段分布放置日志或断点，运行一次后看中断在哪一段，问题范围即可缩小到一个阶段内。

// 阶段日志骨架：把动效调用改造成可观测的序列
function runMotion(target, params) {
  console.log('1. 触发阶段', target, Date.now());
  const el = document.querySelector(target);
  if (!el) throw new Error('目标元素尚未挂载');

  console.log('2. 初始化阶段', params);
  const instance = createMotionInstance(el, params);

  instance.onProgress((progress) => {
    console.log('3. 执行阶段', progress);
  });

  instance.onComplete(() => {
    console.log('4. 回收阶段', el.id);
    instance.destroy();
  });
}

阶段中断在哪一段，就先检查哪一段。中断在第二阶段，大概率是参数或目标元素问题；中断在第三阶段，需要确认执行过程中是否有外部代码修改了元素样式或中断了动画循环。代码中的 createMotionInstance 是示意函数，需要替换为 motion-anything 实际提供的初始化方法或你封装的动效入口。

检查入参类型与元素挂载时机

动效库通常要求数值型参数，但业务代码常常把字符串、未定义值或包含单位的文本传入。建议在动效函数入口增加一道入参校验，对位移、旋转、透明度等关键字段做类型判断，并在调用前打出一份解析后的参数快照。参数一旦出现 NaN 或 undefined，动画表现通常会表现为中途停顿或位置异常。

另一个高频问题是生命周期节点。动效实例在元素尚未进入文档时创建，或在异步组件卸载后才触发执行，都会导致运行时报错。建议在启动动效前检查元素是否已参与布局，例如读取 offsetWidth、getBoundingClientRect 或直接确认 parentNode 是否存在。

用二分隔离法处理复杂调用链

如果动效参数和元素挂载点都正常，但错误仍然出现，可以按依赖顺序把调用链切成两段，先注释掉后半部分，保留前半部分试运行；确认前半段正常后再逐步恢复后半段。如果注释掉某一次调用后错误消失，说明问题集中在该次调用关联的参数或对象上。每轮改动只调整一处，并把改动结果记录到验证清单，避免多因素叠加后失去判断依据。

偶发问题需要记录复现环境

部分动效异常与系统状态相关，例如低电量模式、系统动画强度设置、屏幕刷新率或后台标签页恢复。这类问题在开发环境不容易稳定复现，建议保持运行页面的浏览器版本与操作系统环境固定，反复触发动效并记录复现时的参数快照、页面停留时间与浏览器标签页状态。需要结合目标设备确认是否是兼容性边界，不能只以开发浏览器的行为作为最终结论。