地球自转这个效果放在 Mapbox 里其实是个看起来简单、做起来一堆细节的活儿。我最早是在一个数据大屏项目里被要求加这个效果的产品经理的原话是地球得转起来不然太死板。当时我想着不就是让经度一直加吗半小时搞定。结果真上手才发现速度不稳、拖拽冲突、掉帧、星空背景和大气层穿帮一个接一个。这篇就把 Mapbox 地球自转这件事从头拆一遍它到底适合用在哪、三种实现路径怎么选、核心循环怎么写、参数怎么算、性能怎么压以及我踩过的那些坑。如果你手上正好有个大屏、官网首屏或者地理教学演示需要让地球动起来不管你是刚接触 Mapbox GL JS 的新手还是已经用过几年、想把这个效果做扎实的老手下面的内容应该都能直接拿去用。1. 先想清楚这个自转到底为谁而转动手写代码之前有一件事必须先定下来——你要的是视觉上的地球在转还是地理意义上的视角在移动。这两个说法听起来一样落到实现和后续维护上完全是两码事。1.1 自转效果真正解决的问题静态的地图截图最大问题是没有生命感。人的眼睛对运动物体天生敏感一个缓慢旋转的球体能在不抢走主体信息的前提下把观众的注意力牢牢锁在画面上。这就是为什么几乎所有地理信息大屏、卫星轨道演示、全球业务分布展示首屏都会放一个转着的地球。但它的价值不止于好看。自转带来的第二个好处是展示覆盖范围。一个正面朝向用户的半球能看到的只有一半地球背后的区域永远是盲区。缓慢自转相当于用一个很低的成本把背面的信息轮流送到观众眼前。做全球节点分布、跨时区业务、卫星过境演示这类内容时这一点比单纯的视觉装饰重要得多。第三个好处是暗示可交互。一个静止的三维球体很多人不确定能不能拖。一旦它开始缓慢转动用户潜意识里就知道这东西是活的我能操作。这是个很便宜的交互引导比加一行拖动查看的提示文字有效得多。所以我一般会先问清楚这个自转是纯装饰还是承担信息轮播的功能答案不同速度、暂停策略、是否需要无限循环全都不一样。1.2 三种最常见的落地场景第一种是大屏可视化。特点是无人操作、长时间挂机、分辨率高常见 4K 拼接屏。这种场景下自转要慢通常一圈 60 到 120 秒全程不暂停同时必须考虑长时间运行的稳定性和显存占用。挂机三天崩一次运维就得找你。第二种是产品官网或宣传页首屏。特点是有交互、停留时间短、需要快速出效果。这种场景自转可以稍微快一点一圈 30 到 45 秒足够用户一拖拽就停下来松手后不必自动恢复——因为用户此刻的意图是我要看某个地方不是我要看它转。第三种是教学或演示。比如讲时区、讲昼夜交替、讲经纬网。这种场景对准确性要求高可能需要配合光照方向甚至要能手动控制角速度。我做过一个讲时区的演示自转速度必须严格对应真实地球的角速度每小时 15 度这样观众才能直观理解为什么北京时间比伦敦早 8 小时。提示先确定场景再定速度别反过来。我见过太多项目先写了代码最后发现一圈 10 秒转得人头晕再回头改参数牵一发动全身。1.3 一个必须先澄清的认知转的是相机不是地球Mapbox GL JS 渲染的是一个地理坐标系下的球体地图数据本身是钉在球面上的。你没法真的去旋转这个球体对象——那样做会破坏坐标拾取、破坏图层对齐、破坏所有跟经纬度相关的逻辑。我们实际做的是让相机绕地轴转。具体说是不断改变地图中心的经度值。相机绕着球心转一圈视觉上就是地球自转了一圈。这两个在观感上完全等价但在工程上一个安全、一个灾难。我见过有人图省事直接给 canvas 元素加 CSS 的transform: rotate()。第一次看效果确实转起来了但接下来会连环爆炸鼠标点 A 城市拾取到的是 B 城市图层的经纬度对齐全乱缩放按钮的位置跟画面不同步一旦窗口 resize整个画面错位。这种方案只在纯静态截图 完全禁交互的极端场景下勉强能用其他情况一律别碰。理解了转相机这个前提后面的所有实现就顺了不管是每帧改中心点还是用官方的 spin 插件本质都是同一件事的不同封装。2. 技术路径选型三条路各有各的代价Mapbox 生态里做自转能走的路其实就三条。我把它们摆在一起对比过很多次结论是绝大多数项目应该走第二条但在特定条件下第一条和第三条也有存在价值。2.1 三条路径的横向对比路径核心做法优点缺点适用场景官方 spin 插件引入插件后调用启用方法代码量最少几行搞定可配置项少速度控制粗糙与复杂交互逻辑整合困难快速原型、演示 demo逐帧改中心经度在渲染循环里累加经度并设置中心完全可控速度、暂停、恢复、方向都能自定义需要自己处理时间基准和交互冲突生产项目尤其是大屏和需要精细控制的场景自由相机直接操作相机朝向矩阵可以做倾斜、俯仰等非标准视角学习成本高容易跟内置交互打架需要复合运镜的特殊演示先说官方插件这条路。它的定位很明确让你用最少的代码看到效果。如果你的需求就是页面上有个转着的地球不涉及暂停恢复、不涉及跟其他动画协同那用它完全没问题。但它的问题也明确——速度是固定的几档想精确控制到一圈 90 秒这种粒度基本做不到而且它内部也是逐帧改中心跟你的业务逻辑抢控制权时会很别扭。第三条自由相机路线我个人的建议是除非你确实需要让地球以某个倾斜角度旋转比如模拟从黄道面斜上方俯视的效果否则没必要碰。它绕过了地图的正常交互体系后续维护的人看到那段代码会头疼。2.2 为什么逐帧改中心经度是最稳的方案我最终在项目里统一用的是这个方案理由有三个。第一它走的是地图的正常 API。设置中心点是地图最基础的接口之一所有内置逻辑——图层渲染、坐标转换、事件分发——都会正确处理。你不需要担心它跟别的功能冲突。第二控制粒度足够细。速度想调多慢就多慢想反着转就反着转想在某几个经度上停留一下也可以比如转到某个业务区域时减速。这种灵活性在真实项目里经常被需要。第三跟交互的耦合关系清晰。用户的拖拽本质上也是在改中心点所以暂停自转和恢复自转就是在同一个维度上做开关逻辑非常干净不会出现用户拖完了自转又把画面拽回去的诡异现象。代价是你得自己写循环、自己算速度、自己处理边界。但这两百来行代码换来的是完全可控我认为非常值。2.3 关于 globe 投影的版本前提自转效果在传统的墨卡托投影下也能做——你把经度一直加地图会横向无限滚动。但那不是地球在转那是一张无限长的纸在横向平移。视觉上完全没有球体感只是把地图从右往左推。要做真正的球体自转必须开 globe 投影。Mapbox GL JS 大约从 2.9 版本开始提供 globe 投影支持后续大版本里对大气层、地形的处理逐步完善。所以第一步要确认你的依赖版本够新。npm install mapbox-gllatest或者页面里直接引 CDN 的最新版。这里有个实际经验别用太老的版本硬凑。globe 投影在早期版本里对高纬度区域的形变处理、对极点的渲染都有明显瑕疵用到极地附近的场景比如航线演示时会露馅。至少上到 3.x 会省很多事。3. 核心循环怎么写才不出岔子这部分是整件事的心脏。很多人写出来的第一版能转但会有一堆小毛病速度不稳定、掉帧后变慢、长时间运行变卡。问题几乎都出在怎么计算每一帧转多少上。3.1 初始化一个最小的可运行骨架先给一份能直接跑起来的最小结构。HTML 里放一个撑满视口的容器初始化地图时两个关键参数projection: globe和合适的初始视角。div idearth styleposition:absolute;inset:0;/divmapboxgl.accessToken 你的令牌; const map new mapboxgl.Map({ container: earth, style: mapbox://styles/mapbox/satellite-streets-v12, projection: globe, center: [105, 25], zoom: 1.2, pitch: 0, bearing: 0, attributionControl: false, antialias: false });几个参数的选择理由值得说一下。zoom: 1.2是我反复试出来的甜点值再小一点球体就会缩在画面中央四周大片黑再大一点又会被裁掉边缘看不出是个球。pitch和bearing保持 0是为了让地轴垂直转起来最自然。antialias: false在自转场景下几乎看不出差别但能省不少 GPU 开销——反正在动人眼分辨不出锯齿。attributionControl: false是因为大屏上那行小字很碍眼如果你需要合规保留建议改成自定义位置而不是直接关掉。地图加载完成后再启动循环别在new Map()之后立刻跑那时候样式还没加载完中心点设置会被后续的初始化视角覆盖表现为启动瞬间跳一下。3.2 用时间戳而不是固定帧增量这是最关键的一条经验。新手最常见的写法是function spin() { const c map.getCenter(); map.setCenter([c.lng 0.1, c.lat]); requestAnimationFrame(spin); }看起来没问题每帧加 0.1 度60 帧就是 6 度/秒一分钟一圈。但实际跑起来在配置差一点的机器上你会发现它转得明显慢——因为帧率掉到 30 帧了每帧还是加 0.1速度直接腰斩。更糟的是不同机器上速度不一致演示的时候甲方电脑和你自己的电脑转得不一样快这很尴尬。正确做法是基于真实流逝时间计算角度增量const SPEED_DEG_PER_SEC 6; // 一圈 60 秒 let lastTs null; let running true; function spin(ts) { if (!running) { lastTs null; requestAnimationFrame(spin); return; } if (lastTs null) lastTs ts; const dt Math.min((ts - lastTs) / 1000, 0.1); // 秒封顶防跳变 lastTs ts; const c map.getCenter(); let lng c.lng SPEED_DEG_PER_SEC * dt; if (lng 180) lng - 360; if (lng -180) lng 360; map.setCenter([lng, c.lat]); requestAnimationFrame(spin); } map.on(load, () requestAnimationFrame(spin));speed的单位换算很直白度/秒 每帧增量 × 帧率反过来一圈秒数 360 / 度每秒。想要 90 秒一圈就是 360/90 4 度/秒想要 45 秒一圈就是 8 度/秒。我一般把它抽成配置项方便不同场景直接改数字。那个Math.min(dt, 0.1)的封顶很重要。浏览器切到后台标签页时requestAnimationFrame会被节流甚至暂停切回来那一瞬间dt可能是好几秒不封顶的话地球会嗖地跳过去一大截非常突兀。封顶到 0.1 秒最坏情况就是慢慢挪一小步观感上察觉不到。3.3 经度归一化一个容易被忽略的细节上面代码里那两行if (lng 180) lng - 360是必须的。看起来setCenter对超出范围的经度也能处理但长期累加下去数值会越滚越大浮点精度逐渐丢失表现是转了几十分钟后开始出现轻微的顿挫感。而且如果你把当前经度暴露给其他逻辑用比如显示当前朝向经度不做归一化的数值是没法读的。归一化到 -180 到 180 之间一切就都干净了。这里还有个小选择用-180~180还是0~360。我习惯前者因为这是地图 API 的原生范围跟getCenter()返回值一致省得来回转换。如果你要做从 0 度开始顺时针转这种叙事那就自己加个偏移。3.4 用渲染事件驱动还是 rAF 驱动前面用的是requestAnimationFrame。还有一个选择是监听地图自己的render事件map.on(render, () { // 每帧渲染后触发 });两者区别在于render事件跟地图的渲染节奏严格同步地图不需要重绘时它不触发rAF是浏览器的通用动画节拍跟地图渲染解耦。在自转这个场景里因为我们每帧都在改中心点地图必然要重绘所以两者频率基本一致。但render有个隐患——你在render回调里改中心点会导致下一帧继续触发render形成自驱动的死循环一旦逻辑写错很容易把主线程卡死而且很难调试。相比之下rAF更可控出问题也容易定位。所以我统一用rAF。注意如果你在rAF里既改中心点又做其他重活比如大量 DOM 操作一定把它们分开。混在一起会让每帧耗时超标帧率一掉整个动画的顺滑感就没了。4. 交互冲突自转最容易翻车的地方代码能转只是及格线。真正的难点在于用户开始操作时这个自转该怎么办。处理不好用户体验会非常糟糕。4.1 用户拖拽时必须停下来用户按住地球拖动说明他想看某个具体区域。这时候自转还在继续就等于有人跟你抢方向盘——你往左拖它往右拽画面会抖得让人想砸鼠标。解决方法是监听拖拽开始事件把running置为falsemap.on(dragstart, () { running false; }); map.on(zoomstart, () { running false; });注意zoomstart也要管。用户滚轮缩放的时候如果自转还在跑缩放中心会不断漂移一松手发现放大的位置完全不是自己想看的地方。然后就是恢复策略这个必须分场景定大屏挂机压根不需要恢复逻辑只要检测到任何交互就永久停掉反正大屏没人操作。官网首屏交互后永久停止用户主动操作说明他有明确意图别再自动转回去。教学演示交互后停 5 到 10 秒自动恢复因为演示者可能只是转一下看看接着要继续讲。如果要自动恢复别用setTimeout直接开容易被连续交互打乱节奏。建议用一个最后交互时间戳配合循环内的判断let lastInteract 0; const IDLE_RESUME_MS 6000; map.on(dragstart, () { running false; lastInteract Date.now(); }); map.on(dragend, () { lastInteract Date.now(); }); // 在 spin 循环里 if (!running Date.now() - lastInteract IDLE_RESUME_MS) { running true; lastTs null; // 关键重置时间基准避免一次大跳 }lastTs null这一行是我踩过坑才加的。如果恢复时不清空dt会是暂停时长被Math.min封顶后变成一次 0.1 秒的突跳肉眼能看出来。清空之后下一帧重新取基准就顺滑了。4.2 惯性滑动与自转的叠加问题Mapbox 的拖拽带惯性——松手后画面会继续滑一段再停。这段惯性期间如果你立刻恢复自转两者会叠加滑动的方向被自转强行带偏观感很怪。我的处理是监听moveend而不是dragend等惯性彻底结束再开始计时。moveend在地图完全静止后触发是更准确的信号。map.on(moveend, () { lastInteract Date.now(); });另外还有一个容易漏的点程序化调用也会触发moveend。你的自转循环里调setCenter某些配置下也可能触发移动事件导致自己把自己的计时器刷掉表现为永远不恢复。如果你的自转是通过setCenter实现的通常不会触发moveend因为它不是一次移动操作而是一次瞬时设置但如果你用的是easeTo就一定会。这个区别要记住用easeTo做自转的话事件处理逻辑要格外小心。4.3 暂停时该不该保留当前位置有个细节很多人不处理用户拖完之后自转从当前经度继续还是回到原来的轨道答案显然是前者——从当前经度继续用户不会觉得画面跳回去。这一点上面代码天然满足因为每帧都是读取getCenter()而不是维护一个独立的经度变量。但这也带来一个副作用如果你的自转需要跟某个动画时间轴对齐比如背景音乐、解说词就不能依赖getCenter()得维护独立状态。这种情况极少遇到再说。5. 视觉打磨让球体看起来像个球技术跑通之后剩下的是好不好看。自转效果对视觉细节特别挑剔因为它在动任何瑕疵都会被放大。5.1 星空背景最便宜的质感提升globe 投影下球体之外的区域默认是地图背景色通常是深灰或黑。纯黑太空看着空加一层星空立刻就有宇宙感了。最省事的做法是用 CSS 渐变叠在 canvas 下层#earth::before { content: ; position: absolute; inset: 0; background: radial-gradient(1px 1px at 20% 30%, #fff, transparent), radial-gradient(1px 1px at 70% 60%, #ddd, transparent), radial-gradient(2px 2px at 45% 80%, #fff, transparent), radial-gradient(1px 1px at 85% 15%, #ccc, transparent), radial-gradient(circle at 50% 50%, #0b1020 0%, #05070f 100%); z-index: 0; }要点是星星别太多、别太亮。我一开始堆了几十个点结果背景像噪点图抢了地球的注意力。后来减到十来个稀疏分布再配合一个从中心到边缘的深蓝渐变效果就对了。注意z-index和地图 canvas 的层级关系。上面的伪元素是挂在容器上的得确保地图 canvas 的层级在它之上否则星空会盖住地球。简单做法是给地图容器设z-index: 0伪元素设z-index: -1。5.2 大气层版本差异最大的部分地球边缘那圈雾蒙蒙的蓝光是质感的关键。Mapbox 在新版本里提供了大气效果配置通常在样式加载完成后调用map.on(style.load, () { map.setFog({ color: rgb(10, 20, 40), // 近地面雾色 high-color: rgb(30, 90, 160), // 高空颜色 horizon-blend: 0.08, // 地平线过渡柔和度 space-color: rgb(5, 8, 18), // 太空色 star-intensity: 0.4 // 星空强度 }); });这套参数我是这么调的horizon-blend控制在 0.05 到 0.1 之间太小边缘会硬得像贴图太大整个球会糊。star-intensity给 0.3 到 0.5超过 0.6 就喧宾夺主了。space-color一定要比你 CSS 背景的渐变末端稍亮一点点否则球体边缘和背景之间会有个突兀的断崖。如果你用的是老版本没有这套配置替代方案是给球体外围加一层 CSS 的径向渐变光晕但问题是球体会转、光晕不会转静态光晕在球体转动时不会出错因为球体轮廓不变勉强能糊过去。只是效果明显不如原生的细腻。5.3 昼夜分界线的取舍真实地球有昼夜分界线一半亮一半暗。Mapbox 的雾效配置里有相关能力可以让光照方向跟某个时刻对齐但我一般不建议在这个场景里开。原因很实际一个一半黑的地球暗的那半边的信息完全看不见。而你做自转本来就是为了展示全球信息结果一半时间在展示黑色逻辑上矛盾。而且昼夜分界线的效果在低分辨率屏幕上表现很差暗部区域容易出现色带。除非你的场景就是讲昼夜交替比如教学否则老老实实均匀打光保证任何角度都看得清内容。6. 性能与稳定性挂机三天的考验大屏项目跟普通网页最大的区别是运行时长。普通页面用户看两分钟就走了大屏要连续跑几天。这时候任何微小的资源泄漏都会被放大成雪崩。6.1 帧率不是越高越好我见过有人把速度设成 60 度/秒想让它飞起来。结果在集显机器上直接卡成 PPT。这里的原则是自转这种匀速动画30 帧已经完全够用没必要追 60 帧。控帧的办法很简单在循环里加个时间闸门const FRAME_INTERVAL 1000 / 30; let lastFrameTime 0; function spin(ts) { requestAnimationFrame(spin); if (ts - lastFrameTime FRAME_INTERVAL) return; // 后续逻辑用 ts 计算 dt lastFrameTime ts; }把帧率锁在 30GPU 占用能降下来一大截同时在慢速自转下肉眼完全看不出差别。这个改动在 4K 大屏上效果尤其明显——不锁帧的话风扇会一直狂转。6.2 像素比和分辨率高 DPI 屏幕下Mapbox 默认按设备像素比渲染4K 屏的像素比可能是 2 甚至 3渲染量是普通屏的 4 到 9 倍。这个开销在自转场景完全不值。const map new mapboxgl.Map({ // ... pixelRatio: Math.min(window.devicePixelRatio, 2) });限制在 2 是个折中。往下降画质会明显变糊尤其球体边缘的锯齿会很扎眼不限制又太耗。如果确定是大屏拼接且观看距离远甚至可以降到 1.5观感差异很小。还有一个容易忽略的点maxTileCacheSize。长时间运行 全球自转意味着要加载全世界的瓦片缓存会一直涨。给它设个上限比如 100 左右让地图自己做 LRU 淘汰能有效控制内存增长。6.3 断网、切后台与自动恢复大屏最常见的故障是网络抖动。瓦片加载失败时球体会出现一块块的空白转过去又转回来还是空的。Mapbox 有重试机制但对于长期挂机的场景建议加一层兜底监听error事件如果是瓦片类错误做一次轻量的map.triggerRepaint()或者延迟重设样式。别写得复杂复杂了反而容易出二次问题。另外浏览器标签页切到后台时requestAnimationFrame会被暂停切回来时dt会异常大——这个前面用Math.min封顶已经解决了。但如果你的场景需要页面不可见时彻底停掉自转来省资源可以监听visibilitychange切走时running false切回来时重置时间基准再恢复。7. 常见问题速查把我在项目里遇到的、以及帮同事排查过的问题整理成表遇到问题先对号入座。现象大概率原因处理方式转起来一顿一顿的用的是固定帧增量帧率波动导致速度不均改成基于时间戳计算 dt不同电脑转速不一样同上同上启动瞬间画面跳一下在样式加载完成前就开始改中心点放到load事件之后再启动拖拽时画面抖自转没在拖拽开始时暂停监听dragstart/zoomstart置 false拖完松手后画面被拽回用了easeTo做自转与惯性叠加改用逐帧setCenter转久了开始顿挫经度值无限累加导致浮点精度丢失每帧做-180~180归一化切后台回来地球瞬移dt没有封顶Math.min(dt, 0.1)长时间运行内存持续上涨瓦片缓存无上限设置maxTileCacheSize球体之外的背景是纯灰没有设置雾效或 CSS 背景配置setFog或叠加渐变层高纬度区域变形严重GL JS 版本过老globe 支持不完善升级到 3.x大屏上边缘有黑边容器没有撑满或zoom过大裁切检查容器尺寸和初始 zoom恢复自转时有一次突跳恢复时没重置时间基准lastTs null再补两个不在表里但很典型的。一是地图容器尺寸为 0 导致白屏。在 Vue 或 React 里很常见组件挂载时父容器还没算出高度地图初始化拿到的是 0×0之后再也不自愈。解决办法是在容器尺寸确定后再初始化或者初始化后调一次map.resize()。这个问题跟自转无关但自转项目里踩到的概率极高因为大屏布局往往用了复杂的弹性布局。二是多点触控下的手势冲突。移动端双指缩放时如果自转还在跑缩放中心会飘。处理方式跟拖拽一样监听touchstart停掉即可。测试的时候一定要在真机上测桌面端模拟触摸经常测不出问题。8. 我自己的几个取舍这个效果我前后改过四五版最后稳定下来的配置是这样速度 6 度/秒60 秒一圈帧率锁 30像素比上限 2交互后永久停止自转雾效参数按上面那套给星空用 CSS 稀疏点缀。有几个当时纠结过、后来想明白的点分享一下。关于速度。我一开始设的 3 度/秒120 秒一圈觉得慢一点优雅。上线后反馈是看不出在转。人对缓慢匀速运动的感知是有阈值的低于某个速度就跟静止没区别。最后定在 6 度/秒是能明显感到在动但不至于让人头晕的平衡点。如果你的屏幕特别大、观看距离远可以再放慢到 4 度/秒因为大屏上的角速度感知会不一样。关于自动恢复。我原本很坚持交互后 6 秒自动恢复觉得这样才是完整的产品体验。后来在真实使用中发现用户拖拽往往是有明确目的——他想看某个区域。这时候你过几秒把画面转走是很冒犯的行为。所以现在默认不恢复除非需求方明确要求演示场景。关于要不要用官方插件。我现在的判断标准很简单如果这个项目里自转是唯一的地图功能用插件如果地图上还有其他交互和图层自己写循环。因为一旦有别的逻辑要跟自转协调比如转到某个区域时高亮某个图层插件的黑盒特性会让你非常难受。最后提一句扩展方向自转这套循环骨架其实可以直接复用做别的动画比如沿着某个纬线缓慢平移、周期性切换视角、或者配合数据更新做扫描式的高亮。核心就是那个基于时间戳的帧循环把它抽成一个独立的小模块后面加什么效果都是往里塞回调的事不用每次重写。