企业官网建设流程全解析

把模型动画加载到 Cesium，听起来是个“三十秒搞定”的小功能，结果我上周被一个“模型显示正常、动画就是不动”的问题卡了大半天。用fromGltfAsync加载一个带走路动作的 glb，模型在地球上摆好了姿势，材质、光照、阴影全对，唯独整个模型像被按了暂停键。断点、翻文档、逐个属性查下来，最后发现原因往往不在模型本身，而在异步加载后的调用时机、activeAnimations有没有真正激活，以及viewer.clock有没有真的走起来。这篇文章就把我这次排查的完整过程记录下来，从现象到原理，再到可以直接抄的检查顺序，给同样被动画卡住的朋友做个参考。

1. 现象与排查前的三个判断

1.1 先分清“模型没加载出来”和“模型加载了但没动”

动画不播其实分两类现象。一类是白屏、黑模型、半透明模型、加载到一半卡住，这类大多跟文件资源、路径、网络请求、纹理加载有关，本质上不是动画问题。另一类是模型完整显示，纹理也正常，模型甚至能拾取点击，但时间线里的动作一动不动。这篇文章主要聊第二种，但排查时建议先把第一种排除掉。

Cesium 的调试第一步永远是打开浏览器开发者工具看 Network 面板。可以看到 glb / gltf 本身的请求是否 200，关联的 .bin、纹理图片是否 404。如果模型是从一个大的目录里加载，Resource的 basePath 解析错误会直接导致资源缺失；很多时候模型没出来不是 Cesium 的问题，而是相对路径写错。

确认模型已经正确渲染之后，再往动画方向查。这里有一个非常容易误判的点：模型静止并不代表动画系统完全没工作，可能只是时钟没走、动画没激活、或者激活了但时间没有前推。这三种情况表现差不多，但处理方式完全不同。

1.2 动画播放的三层条件：资源、集合、时钟

要在一个 3D 引擎里让 glTF 动画跑起来，至少得有这三层条件同时满足。

第一层是资源层。glTF / glb 文件里必须真的有animations数组，并且动画 channel 指向的 node、skin、accessor 数据都完整。资源损坏或导出时没勾选动画，后面怎么调都没用。

第二层是运行时动画集合。Cesium 把 glTF 里的动画解析成model.animations这个集合，但这只是“可以用”的动画列表，不代表“正在播放”。真正要让动画开始播放，需要把动画放进model.activeAnimations。这个关系很像唱片和唱机：model.animations是唱片架上放着的唱片，model.activeAnimations.add才把唱片放到唱机上转起来。

第三层是时间驱动。Cesium 的模型动画不是自驱的，它依赖一个外部时钟推进时间轴。如果viewer.clock.shouldAnimate为 false，或者时钟的currentTime已经不在动画区间里，动画即使激活了，每一帧的时间仍然不变，表现就是模型卡在某一帧。

这三层条件缺一不可。我发现很多“动画不播放”其实不是某个神秘 bug，而是其中一层没有满足。后面的内容就一层层拆开看。

2. fromGltfAsync 的异步加载机制与就绪时序

2.1 老 API 与新 API 的差异

Cesium 里加载 glTF 模型的接口经历过几个版本。比较早期常用的是Cesium.Model.fromGltf，它返回一个Model实例，但并不代表资源已经全部加载完成。想要在模型真正就绪后操作，得监听readyEvent或者readyPromise。如果没等 ready 就去访问model.animations，拿到的是一个空集合。

现在更推荐的是Cesium.Model.fromGltfAsync，它是异步接口，返回 Promise。await完成之后，模型资源已经准备好了，这时候再访问model.animations才是安全的。这个差异看起来很小，却是很多调用时序错误的根源。

我举个例子你就明白了。有朋友用旧接口，代码写成这样：

const model = Cesium.Model.fromGltf({ url: 'walk.glb' }); viewer.scene.primitives.add(model); model.activeAnimations.addAll({ loop: Cesium.ModelAnimationLoop.REPEAT });

这段代码在某些版本里可能“碰巧”能跑，因为模型资源加载很快，addAll 执行时动画已经解析进去了。但如果 glb 比较大、网络慢一点，addAll 先执行，模型动画还没解析完，就会出现“model.animations.length 是 0”的情况。这不是接口本身的问题，而是使用时机的问题。

2.2 新接口也容易犯的时序错误

fromGltfAsync虽然解决了“资源是否 ready”的问题，但如果你把异步流程写错，照样会踩坑。最常见的是这样：

let model; async function loadModel() { model = await Cesium.Model.fromGltfAsync({ url: 'walk.glb' }); } loadModel(); viewer.scene.primitives.add(model);

这段代码的问题在于loadModel()是异步的，await还没有返回，后面的viewer.scene.primitives.add(model)就已经执行了。此时model还是 undefined，浏览器直接报错，或者模型没加到场景里。

正确的写法是把后续操作都放进异步流程里，或者用then串起来：

async function loadWalkingModel(url) { const model = await Cesium.Model.fromGltfAsync({ url }); viewer.scene.primitives.add(model); console.log('animation count:', model.animations.length); for (let i = 0; i < model.animations.length; i++) { const anim = model.animations.get(i); console.log('index', i, 'name:', anim.name, 'duration:', anim.duration); } model.activeAnimations.addAll({ speedup: 1.0, loop: Cesium.ModelAnimationLoop.REPEAT }); viewer.clock.shouldAnimate = true; viewer.clock.multiplier = 1.0; }

这里面还有个细节：fromGltfAsync的 Promise 只在模型“数据解析完成”后 resolve，但如果模型纹理加载采取了异步流式策略，某些纹理可能还在加载中。对动画来说，纹理加载晚一点通常不影响关键帧播放。真正影响动画的是动画数据，而不是纹理贴图。

2.3 资源路径与模型文件本身也可能骗你

还有一类情况是“模型动了，但不是你想的那个模型”。比如从某工具导出的 glb 默认没勾选“导出动画”，你在 Cesium 里加载后模型确实显示，但model.animations.length为 0。这个问题经常被误判成 API 或者时钟问题。

排查方法不复杂，用 Node 就能快速看 glTF 的结构。glb 是二进制容器，里面嵌着 JSON chunk，可以用解析库读出来，直接看 JSON 里有没有animations字段。如果连 JSON 里都没有，那就不是 Cesium 写错了，老老实实回去重新导出。

另外，如果模型是.gltf + .bin + 纹理的拆分格式，动画数据通常在.bin里。.bin文件少了，或者导出时 keyframe 数据被剥离，模型会有形但动不了。我在实际项目中遇过一次：有人为了方便预览，把 GLTF 文件拷到服务器，但没拷贝同目录的.bin，结果模型要么不显示，要么显示出来只有一个静态姿势。这种问题跟fromGltfAsync无关，但因为它发生在加载阶段，很容易让人误以为是加载接口的问题。

3. 动画的“存在”和“播放”是两件事

3.1 model.animations 只是“可播放动画列表”

Cesium 把 glTF 中的每个动画包装成一个ModelAnimation对象，放在model.animations这个ModelAnimationCollection里。你可以通过length获取动画数量，通过get(index)获取具体某个动画。

我调试时习惯先打印这一段：

console.log('model.animations.length:', model.animations.length); for (let i = 0; i < model.animations.length; i++) { const anim = model.animations.get(i); console.log(i, anim.name, anim.duration); }

如果这段输出为 0，说明模型里根本没有动画，不用再往下面查。如果输出大于 0，比如看到0 'Walk' 2.4，说明 glTF 文件自带一个名叫 Walk、时长 2.4 秒的动画。这时候动画“存在”了。

关键是：存在不等于播放。很多新手看到model.animations.length大于 0，就以为动画会自动开始。实际上 Cesium 在加载模型后，不会主动让任何动画跑起来。你需要把它增加到model.activeAnimations集合里。

这个设计其实是合理的。因为一个模型可能带十几个动画，比如待机、走路、跑步、攻击、死亡。如果全部默认播放，角色就会同时又走路又攻击又死亡，非常混乱。Cesium 把“选择播哪个”和“怎么播”交给调用方，是更可控的。

3.2 activeAnimations.addAll 与 add 的正确使用

model.activeAnimations是另一个ModelAnimationCollection，但语义完全不同。它管理的是“当前正在播放的动画实例”。把同一个动画加进去一次，就是一个播放实例；可以设置倍速、循环模式、起始时间、延迟等。

如果只需要让动画随便动起来，最快的方式是addAll：

model.activeAnimations.addAll({ speedup: 1.0, loop: Cesium.ModelAnimationLoop.REPEAT });

它会遍历model.animations里所有动画，全部加入播放列表。这种写法适合只有一两个动画、并且这些动画可以同时播的场景。

如果只想播某一个动画，用add：

const anim = model.activeAnimations.add({ name: 'Walk', speedup: 1.0, loop: Cesium.ModelAnimationLoop.REPEAT });

注意add的name对应的是刚才打印出来的动画名。假如模型里动画名是Take 001，你写Walk，就会收到 undefined 或找不到动画，表现同样是模型不动。

activeAnimations.add的返回值是当前启动的播放实例，可以做事件监听，比如动画播完、被移除等。实际项目里做角色状态切换，通常建议先removeAll，再add目标动画，避免旧动画和新动画叠加。

3.3 动画名为空和多动画叠加的坑

我在一些从建模软件导出的模型里见过很奇怪的现象：model.animations.length是 1，anim.name却是一个空字符串，或者是一串乱起的名字。通过名称去add时就悲剧了，永远匹配不上。

这种时候不要硬通过名字匹配，可以用addAll，或者拿到具体索引后直接操作。Cesium 的add如果不传name，默认会尝试添加第一个动画，所以空名场景下也可以写：

model.activeAnimations.add({ speedup: 1.0, loop: Cesium.ModelAnimationLoop.REPEAT });

多动画叠加是另一类常见问题。有些角色模型每套动作都是独立的，但如果你用addAll一次性全部播放，会出现模型同时执行多个骨骼动画，结果看起来像“抽筋”一样抖动或者乱飞。这时就不是“不播放”了，而是“播放混乱”。如果是这种表现，先改成只播一个动画，确认基础动画正常，再逐个叠加。

4. 时钟：Cesium 动画的真正驱动器

4.1 为什么 Cesium 没有默认播放键

在 3D 编辑器里，时间轴一般默认是走的，动画自然就会播放。但 Cesium 面对的是完整的虚拟时间体系，它要负责太阳光照、地球自转、动态标绘、粒子系统等很多依赖时间的功能，所以对时间的前进非常克制。

Viewer自带一个clock对象，属性包括currentTime、startTime、stopTime、multiplier、shouldAnimate。其中shouldAnimate默认通常是 false。这意味着即使模型加进去了、动画也激活了，时钟每一帧的时间值都不变，动画就会被钉死在当前帧。

把这个开关打开，是最容易被忽略的一行代码：

viewer.clock.shouldAnimate = true;

Cesium 的模型动画在更新时，会从当前帧对应的世界时间中计算 local time，然后去采样 glTF 关键帧。时钟不前进，关键帧采样点永远不变，运动自然就停了。

你可以把这个机制理解成拍定格动画：摄像机、灯光、角色都摆好了，但只要你没有“翻页”，画面就固定在一个姿势上。shouldAnimate就是那个“翻页开关”。

4.2 时钟范围、倍速和停止帧的坑

只打开shouldAnimate还不一定万事大吉。如果把currentTime设在了动画时间区间之外，模型可能仍然不懂。比如某个模型动画只有 0 到 2.4 秒，而 Cesium 时钟被拨到了 1000 秒以后，那就只能看到最后关键帧或第一关键帧。

我排查时一般会把这三个值一次性打出来：

console.log('clock:', { shouldAnimate: viewer.clock.shouldAnimate, currentTime: viewer.clock.currentTime.toString(), startTime: viewer.clock.startTime.toString(), stopTime: viewer.clock.stopTime.toString(), multiplier: viewer.clock.multiplier });

如果时间已经走到stopTime附近，并且currentTime到了边界，后续时间不会继续增长，动画自然卡住。这时候可以手动把当前时间重置，或者调整时钟范围。

倍速也是一个大坑。viewer.clock.multiplier是全局时间倍速。有人为了模拟真实时间，把它设成 1.0，这没问题；但当它被设成 0 或极小值时，模型动画几乎不可见。我见过一个项目里的代码，为了做“暂停业务逻辑”，直接改了multiplier = 0，结果角色动画全部停了。后来排查很久才发现是倍速问题。

模型动画自身还有speedup参数，它单独控制当前动画播放速度，不受模型几何属性影响。如果speedup设成 0，即使全局时钟正常，这个动画也纹丝不动。

4.3 自建场景时时钟要自己 tick

很多朋友用的是new Cesium.Viewer(container)，这没问题，viewer 内部会自动驱动时钟。但如果有人为了减少开销，自己创建Scene、Camera、Clock，那就得手动推进时间。

场景每帧 render 前，通常需要调用clock.tick()更新当前时间。假如你只在 requestAnimationFrame 里调scene.render()，没有 tick，动画一样不会动。

我自己踩过一次：在离屏渲染场景里用Cesium.Scene做缩略图，模型加载好后，动画始终不动。后来发现是渲染循环里只调用了scene.render()，没有把clock.tick()放进去。加上之后一切都正常。

所以排查时，先问一个问题：当前这个scene的时钟到底是谁在推进？如果是Viewer，那么viewer.clock是对的。如果是自己渲染的，看看自己的帧循环有没有更新时间。

5. 排查清单与调试实录

5.1 从“动画集合”开始逐层确认

这里分享一套我常用的排查顺序，按这个来基本不会漏。

第一步，确认模型已经加载并渲染出来。把模型加入scene.primitives后，看一眼场景里有没有模型，网络请求有没有报错。

第二步，打印model.animations.length。如果没有动画，回去检查 glTF 导出参数。

第三步，打印所有动画的名称和时长。确认你打算播的那个动画确实存在。如果名称是空或者不符合预期，考虑用索引或者addAll。

第四步，调用activeAnimations.addAll或add。不要只看“调用了”就觉得是播了，检查返回值是否正常。如果add返回 undefined，说明名字不对，或者模型动画集合为空。

第五步，设置viewer.clock.shouldAnimate = true，并确认multiplier大于 0。如果你发现模型某个位置不动，但旋转或平移很诡异，再检查clock.currentTime是否已经越界。

第六步，检查模型自身的位置、朝向和相机。有些时候动画其实在播，但模型正处于地面以下，或者旋转后背面朝上，视觉上看起来像没动。这不算动画问题，但经常会被当成动画问题排查。

5.2 常见问题速查表

这张表基本覆盖了我遇到过的绝大多数情况。排查时不用上来就问“为什么模型不动”，先对着表确认是哪一层出了问题。

5.3 实际调试中的三个弯路

先讲第一个弯路。有一个客户模型，加载到 Cesium 里之后一直显示“辅助姿势”，也就是我们常说的 T-pose。我在浏览器里确认model.animations.length正常，动画名称也正常，addAll也调了，但模型就是不动。最后发现，这个 glTF 文件里的骨骼动画skins引用的 joint 节点不完整，有一个 bone 的 accessor 数据在导出时被剥离了。这个属于模型本身问题，不是 Cesium 的加载接口问题。换了一个完整导出的模型后，动画立刻正常。

第二个弯路发生在动画名为空的情况。我从某建模工具导出的模型，动画名叫空字符串。代码里写name: 'Walk'一直匹配不到，模型自然不动。后面我把名称打印出来，发现anim.name是空，于是改用add不传名字，动画就好了。

第三个弯路是时钟问题。有人把一段动画设置成循环播放，但发现播放一段时间后角色停在半空中。原因是viewer.clock.currentTime已经超过了stopTime，后续时间不再增长，循环也就无从谈起。重置currentTime或者把stopTime调远一点就解决了。当时如果只盯代码不打印时钟，可能还要纠结很久。

这些弯路看起来都很简单，但都真实存在于乱七八糟的业务代码里。动画问题十有八九不是单个函数写错，而是多层条件配合不到位。

6. 最后再留三个排查习惯

我用新接口加载带动画的模型时，现在固定会做三件事。

第一，永远在await之后去拿model.animations。不要在任何异步流程外部提前访问模型属性。这能避开 80% 的加载时序问题。

第二，把viewer.clock.shouldAnimate = true和activeAnimations.add写在同一个函数里，作为一组固定动作。这样如果某人把模型加载逻辑复制到别处，至少不会出现“动画加了但时钟没开”这种半吊子状态。

第三，遇到不播放问题，第一时间打印三样东西：model.animations.length、动画名称列表、clock当前状态。三样一出来，问题基本缩小到一个很小的范围，不用瞎猜。

动画不播放不是随机 bug。它只是资源、集合、时钟这三个条件中的某一个没搭上。把这篇文章里的排查顺序走一遍，大多数fromGltfAsync动画问题都能落地解决。