1. 从零开始：理解Cesium动态轨迹回放的核心
想象一下，你手头有一架无人机的飞行数据，或者一艘货轮的航行日志，你想在一个逼真的三维地球上，像看电影一样，把这段旅程重新播放出来。模型不仅要沿着预定的路线移动，你还能控制播放速度，让它快进、慢放，甚至循环播放。这就是Cesium动态轨迹回放要帮你实现的事情。听起来很酷，对吧？其实它的核心原理并不复杂，就像我们小时候玩的“连点成线”游戏，只不过这次我们把“点”换成了三维空间中的坐标和对应的时间戳。
Cesium实现这个功能，主要靠两个“黄金搭档”：SampledPositionProperty和Clock对象。你可以把SampledPositionProperty想象成一个超级智能的“路径记录仪”。它不仅仅记录了一串位置坐标（比如经度、纬度、高度），还为每一个位置都精确地绑定了一个时间点。当你问它“在下午3点05分的时候，无人机在哪里？”时，它能立刻给出答案。更厉害的是，即使你的数据点不够密集，它还能在两个已知点之间进行平滑的插值计算，让模型的移动看起来连续自然，而不是一跳一跳的。
而Clock对象，就是整个场景的“导演”兼“场记”。它控制着三维地球这个舞台上的时间流逝。是正常播放，还是2倍速快进？播放到终点是停下来，还是倒回去重新开始？这些都由Clock说了算。它手里握着“时间轴”，每走一步，就去通知SampledPositionProperty：“嘿，现在时间到了X点X分，该告诉我模型应该出现在哪个位置了。” 然后Cesium的渲染引擎就会把模型画到对应的位置上。我们所有关于时间控制的高级玩法，比如加速、循环、暂停，本质上都是在和这个Clock“导演”沟通。
所以，整个流程的骨架非常清晰：准备带时间戳的路径数据 -> 用SampledPositionProperty把它们“喂”给模型实体 -> 用Clock控制时间流动来驱动回放。接下来，我们就一步步把这个骨架填充上血肉，让它真正动起来。无论你是想模拟无人机巡检、车辆轨迹分析，还是游戏剧情演示，这套方法都是通用的起点。
2. 搭建舞台：初始化地图与准备轨迹数据
万事开头难，但在Cesium里，开个好头却异常简单。首先，你得有个能显示三维地球的“舞台”。如果你还没有Cesium的访问令牌（Access Token），需要去Cesium官网注册一个，它是加载在线地形和影像服务所必需的。拿到令牌后，初始化一个Viewer对象，你的三维舞台就搭好了。
import * as Cesium from 'cesium'; // 替换成你自己的Ion Access Token Cesium.Ion.defaultAccessToken = '你的令牌字符串'; // 初始化三维地球视图，'cesiumContainer'是你HTML页面中一个div的id const viewer = new Cesium.Viewer('cesiumContainer', { terrainProvider: Cesium.createWorldTerrain(), // 使用真实世界地形 animation: true, // 显示动画控件（播放/暂停按钮等） timeline: true, // 显示时间轴控件 vrButton: false, // 根据需求决定是否显示VR按钮 }); // 可以设置一个初始视角，比如飞到中国上空 viewer.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(116.4, 39.9, 15000000), // 北京上空 orientation: { heading: Cesium.Math.toRadians(0), pitch: Cesium.Math.toRadians(-90), // 垂直向下看 roll: 0.0 } });舞台搭好，接下来就是规划“演员”（你的模型）要走的路。轨迹数据通常来自你的业务系统，比如从数据库里查出来的一系列GPS点。这里我假设你已经拿到了一个数组，里面是[经度， 纬度， 高度]这样的结构。在Cesium的世界里，我们需要把常见的地理坐标（WGS84）转换成它内部使用的笛卡尔坐标（Cartesian3）。
// 假设这是你的原始路径数据，每个点是一个 [经度, 纬度, 高度(米)] 数组 const gpsPoints = [ [116.3, 39.9, 1000], [116.31, 39.91, 1200], [116.32, 39.92, 1100], // ... 更多点 ]; // 用于存储转换后的Cesium笛卡尔坐标 const positions = []; gpsPoints.forEach(point => { // Cesium.Cartesian3.fromDegrees 是转换神器 const cartesianPosition = Cesium.Cartesian3.fromDegrees(point[0], point[1], point[2]); positions.push(cartesianPosition); });为了让轨迹在三维场景中更直观，我强烈建议你把这条路径线也画出来。这就像在地上先画好跑道，再让飞机去飞，对于调试和展示都极其有用。用viewer.entities.add添加一个Polyline实体即可。
// 添加轨迹线实体 const pathEntity = viewer.entities.add({ name: '飞行轨迹', polyline: { positions: positions, // 使用刚才转换好的坐标数组 width: 3, material: new Cesium.PolylineOutlineMaterialProperty({ color: Cesium.Color.CORNFLOWERBLUE, outlineWidth: 1, outlineColor: Cesium.Color.WHITE }), // clampToGround: true // 如果希望线贴在地形上，可以设为true，但注意高空飞行轨迹可能不适合 } });踩过的一个坑是：如果你的轨迹点高度变化很大（比如无人机爬升），clampToGround一定要设为false，否则线会被强制压到地形表面，看起来就不对了。现在，你的地图上应该已经出现了一条清晰的蓝色轨迹线，舞台和跑道都已就位，主角模型即将登场。
3. 让模型动起来：SampledPositionProperty与Clock的深度配合
现在到了最核心的环节：让一个3D模型沿着我们画好的线动起来。这里的关键就是创建一个SampledPositionProperty对象，并把它“安装”到我们的模型实体上。
首先，我们加载一个模型。Cesium支持 glTF/GLB 格式，这是三维界的“JPEG”，通用性很好。你可以从网上找一些免费的无人机、飞机、汽车模型，或者用建模软件自己制作。
// 创建 SampledPositionProperty，它将管理模型位置随时间的变化 const positionProperty = new Cesium.SampledPositionProperty(); // 添加模型实体，并将其位置属性绑定到 positionProperty const movingEntity = viewer.entities.add({ id: 'myMovingDrone', // 给实体一个ID，方便后续查找和控制 name: '无人机', position: positionProperty, // 核心！位置由positionProperty动态驱动 // 让模型始终朝向运动方向，这个属性非常实用 orientation: new Cesium.VelocityOrientationProperty(positionProperty), model: { uri: './models/drone.glb', // 你的3D模型文件路径 scale: 2.0, // 调整模型大小 minimumPixelSize: 64, // 保证模型在远处也能看见 runAnimations: true, // 如果模型自带动画（如螺旋桨转动），可以播放 }, // 可以添加一些标签或说明 label: { text: '无人机01', font: '14px sans-serif', style: Cesium.LabelStyle.FILL_AND_OUTLINE, outlineWidth: 2, verticalOrigin: Cesium.VerticalOrigin.BOTTOM, pixelOffset: new Cesium.Cartesian2(0, -40) // 让标签显示在模型下方 } });绑定了位置属性后，模型现在听命于positionProperty了。但positionProperty自己还不知道什么时候该出现在哪里。我们需要告诉它时间表。这就是引入Clock的原因。我们先设定整个动画的起止时间。
// 定义动画总时长，比如300秒飞完全程 const totalSeconds = 300; // 设定动画开始时间为“现在” const startTime = Cesium.JulianDate.fromDate(new Date()); // 计算结束时间 = 开始时间 + 总秒数 const stopTime = Cesium.JulianDate.addSeconds(startTime, totalSeconds, new Cesium.JulianDate()); // 配置Cesium的时钟 viewer.clock.startTime = startTime.clone(); viewer.clock.stopTime = stopTime.clone(); viewer.clock.currentTime = startTime.clone(); // 设置当前时间为开始时间 viewer.clock.clockRange = Cesium.ClockRange.LOOP_STOP; // 播放到终点后，循环播放 viewer.clock.multiplier = 1; // 时间流逝倍数，1为正常速度好了，导演（Clock）已经知道这场戏要从几点拍到几点。现在需要场记（positionProperty）把每个时间点演员该站的位置记录下来。我们需要把之前转换好的positions坐标数组，按照时间均匀地（或按实际时间戳）分配给positionProperty。
// 假设我们有N个路径点，将总时间平均分配给这些点 positions.forEach((position, index) => { // 计算每个点对应的时间：开始时间 + (索引 * 每个点间隔时间) // 这里假设每个点间隔时间相同，总时长除以点数。更真实的情况应使用实际的时间戳。 const pointInterval = totalSeconds / (positions.length - 1); const sampleTime = Cesium.JulianDate.addSeconds(startTime, index * pointInterval, new Cesium.JulianDate()); // 将 (时间, 位置) 这个“样本”添加到属性中 positionProperty.addSample(sampleTime, position); });到这里，所有准备工作就完成了。当你把viewer.clock.shouldAnimate设为true，或者点击Cesium界面上的播放按钮时，奇迹就会发生：时钟开始走动，每走一秒，就会去positionProperty里查询当前时间对应的位置，然后更新模型实体的位置。你的无人机模型就会沿着轨迹线平滑地飞起来了！为了让视野跟上模型，可以设置相机跟踪：viewer.trackedEntity = movingEntity;。
4. 高级时间控制：实现加速、循环与交互播放
基础的回放功能实现后，我们就可以玩点更花的了。Cesium的Clock对象提供了非常丰富的API，让我们能像操作一个视频播放器一样，精细控制这段三维动画。
首先是速度控制。这可能是最常用的功能了。viewer.clock.multiplier这个属性直接控制了时间流逝的倍数。把它设为2，时间就以两倍速前进；设为0.5，就是慢动作播放；设为0，时间就暂停了。在实际项目中，我经常做一个滑块控件绑定到这个值上，让用户自由调节回放速度。
// 一个简单的速度控制函数 function setPlaybackSpeed(multiplier) { if (viewer.clock && !isNaN(multiplier)) { viewer.clock.multiplier = multiplier; console.log(`播放速度已设置为: ${multiplier}x`); } } // 例如，在按钮点击事件中调用 // document.getElementById('speedUpBtn').onclick = () => setPlaybackSpeed(5); // 5倍速 // document.getElementById('pauseBtn').onclick = () => setPlaybackSpeed(0); // 暂停 // document.getElementById('normalBtn').onclick = () => setPlaybackSpeed(1); // 正常速度其次是播放模式。viewer.clock.clockRange决定了当时钟走到终点时的行为。它有三个选项：
Cesium.ClockRange.LOOP_STOP：这是我个人最喜欢用的。播放到终点后，自动跳回起点，并停止。需要用户再次点击播放才会开始新一轮循环。这个逻辑很清晰，适合分析演示。Cesium.ClockRange.LOOP：播放到终点后，立即跳回起点继续播放。适合做无人值守的循环展示。Cesium.ClockRange.CLAMPED：播放到终点后，就停在终点不动了。Cesium.ClockRange.UNBOUNDED：不受起止时间限制，会一直往后走。这个模式要小心使用，因为你的positionProperty可能没有定义终点之后的位置数据。
然后是交互控制。除了用Cesium自带的动画控件，我们完全可以自己定制一套控制面板。核心就是控制viewer.clock.shouldAnimate（开始/暂停）和viewer.clock.currentTime（跳转）。
// 自定义播放/暂停 function togglePlayPause() { viewer.clock.shouldAnimate = !viewer.clock.shouldAnimate; } // 跳转到特定百分比（比如进度条拖动） function jumpToPercentage(percent) { const totalTime = Cesium.JulianDate.secondsDifference(viewer.clock.stopTime, viewer.clock.startTime); const targetSeconds = totalTime * percent; const targetTime = Cesium.JulianDate.addSeconds(viewer.clock.startTime, targetSeconds, new Cesium.JulianDate()); viewer.clock.currentTime = targetTime; } // 监听时钟的每一次跳动，可以在这里更新UI（比如当前时间显示） const clockTickListener = viewer.clock.onTick.addEventListener(function(clock) { const current = clock.currentTime; const total = Cesium.JulianDate.secondsDifference(clock.stopTime, clock.startTime); const passed = Cesium.JulianDate.secondsDifference(current, clock.startTime); const progress = (passed / total * 100).toFixed(1); // 更新一个自定义的进度条 // document.getElementById('progressBar').value = progress; // document.getElementById('timeDisplay').innerText = `进度: ${progress}%`; });最后是性能与体验优化。当轨迹点非常多（比如上万点），或者模型很复杂时，直接全部添加样本可能会导致初始化卡顿。一个实用的技巧是“抽稀”，即在保持轨迹形状大致不变的前提下，剔除一些冗余的点。另外，对于超长轨迹，可以考虑动态加载数据，只加载当前时间窗口附近的轨迹点样本到positionProperty中，这需要更复杂的数据管理逻辑。在模型方面，尽量使用轻量化的glTF模型，并合理设置minimumPixelSize和maximumScale，以保证在视野拉远时不会过度消耗性能。
5. 实战技巧与常见问题排查
理论讲完了，我们来点干货。在实际项目中实现轨迹回放，你大概率会遇到下面这些问题。我把踩过的坑和解决方案都整理在这里，希望能帮你节省大量调试时间。
第一个常见问题：模型位置飘忽不定或抖动。这通常是因为你的轨迹点坐标参考系不统一，或者高度值异常。确保所有GPS点都转换成了Cesium笛卡尔坐标。另外，检查一下你的模型原点（pivot）是否在重心位置。有时候模型文件自身的原点在脚部，飞行起来就会显得很奇怪。可以在建模软件中调整，或者在Cesium中用modelMatrix属性进行变换补偿。
第二个问题：轨迹播放不流畅，有卡顿感。除了前面提到的数据抽稀和模型优化，还要关注Clock的multiplier设置。当速度倍数过高（比如1000倍）时，Cesium每一帧需要计算的时间跨度极大，如果SampledPositionProperty的插值算法比较复杂，就可能掉帧。可以尝试调整positionProperty.setInterpolationOptions，使用更简单的插值算法，比如Cesium.LinearApproximation（线性插值），它在速度和精度之间是个不错的折中。
positionProperty.setInterpolationOptions({ interpolationDegree: 1, // 1次插值，即线性 interpolationAlgorithm: Cesium.LinearApproximation });第三个问题：时间轴（Timeline）显示不正常。有时候你会发现时间轴控件上一片空白，或者时间范围不对。这几乎总是因为viewer.clock的startTime和stopTime没有正确设置，或者设置的时间格式不对。务必使用Cesium.JulianDate来操作时间。初始化后，可以调用viewer.timeline.zoomTo(viewer.clock.startTime, viewer.clock.stopTime);来让时间轴缩放至合适范围。
第四个问题：如何基于真实时间戳回放？前面的例子是假设时间均匀分配。但真实数据每个点都有精确的UTC时间戳。这时，你需要用真实的时间差来计算样本时间。
// 假设你的数据是：{lon: 116.3, lat: 39.9, height: 1000, timestamp: '2023-10-01T08:00:00Z'} const realStart = Cesium.JulianDate.fromIso8601(dataPoints[0].timestamp); const start = Cesium.JulianDate.fromDate(new Date()); // 回放开始的“现在” dataPoints.forEach((point, index) => { const pointRealTime = Cesium.JulianDate.fromIso8601(point.timestamp); // 计算该点相对于真实起始点的时间偏移（秒） const secondsFromStart = Cesium.JulianDate.secondsDifference(pointRealTime, realStart); // 在回放中，这个偏移量被加到“现在”这个起始点上 const sampleTime = Cesium.JulianDate.addSeconds(start, secondsFromStart, new Cesium.JulianDate()); const position = Cesium.Cartesian3.fromDegrees(point.lon, point.lat, point.height); positionProperty.addSample(sampleTime, position); }); // 设置Clock的起止时间为回放的起止时间 const totalDuration = Cesium.JulianDate.secondsDifference( Cesium.JulianDate.fromIso8601(dataPoints[dataPoints.length-1].timestamp), realStart ); viewer.clock.startTime = start.clone(); viewer.clock.stopTime = Cesium.JulianDate.addSeconds(start, totalDuration, new Cesium.JulianDate());第五个问题：内存泄漏。如果你需要动态创建和销毁多个轨迹回放，切记要清理监听器和实体。不用的onTick事件监听器要用removeEventListener移除，不用的实体要用viewer.entities.removeById或viewer.entities.remove从集合中删除。否则，页面会越来越卡。
// 清理工作 function cleanupMovingEntity(entityId) { const entity = viewer.entities.getById(entityId); if (entity) { viewer.entities.remove(entity); } // 如果之前监听了clock.onTick，也要移除 // viewer.clock.onTick.removeEventListener(yourListener); }把这些细节处理好，你的轨迹回放功能就会既稳定又流畅。最后再分享一个小心得：在开发过程中，多利用Cesium的Cesium Inspector工具（在浏览器控制台输入viewer.extend(Cesium.viewerCesiumInspectorMixin);可以开启），它可以实时显示实体、性能指标，是调试的利器。轨迹回放本质上是对时空数据的一种可视化，当你看到模型按照预想的方式在三维时空中穿梭时，那种成就感是非常直接的。
