第一次接到首屏放一个会自转的地球这个需求我的判断是三分钟收工Mapbox GL JS 早就支持球体投影加个开关的事。真上手才发现翻遍配置项也找不到一个叫 autoRotate 或者 spin 的参数。球体投影只负责把地图画成一个球至于这个球要不要转、转多快、用户手指按下去时让不让路、切到后台再切回来会不会突然窜出去半圈全部都得自己写。这篇就把我给几个展示页做 Mapbox 地球自转的全过程摊开讲。从为什么没有现成开关讲到直接能抄的自转内核再讲用户手势抢占、后台标签页的时间戳跳变、低端机掉帧、观感调优最后附一张症状对照表。前端刚接触地图 SDK 的同学可以照着代码跑通已经在用 Mapbox 但被自转僵死拖拽打架切标签页回来瞬移折磨过的可以直接跳到第 3、4 章。1. 球体投影只解决像不像地球自转得自己造1.1 globe 投影接管的是渲染不是相机运动很多人对这件事的第一层误解是以为打开了 globe地图就变成一个可以转的 3D 球剩下的交给引擎。实际上球体投影改变的是投影管线——把原本平面墨卡托的瓦片贴到一个球面上再投影到屏幕顺带处理地平线、大气、星空、背面剔除。它不产生任何自动运动。而我们在视觉上看到的地球自转本质上是相机经度在持续变化。地图中心点每向前推进一点经度球体看起来就转过一点角度。这个动作在 API 层面上等同于一连串的setCenter或者更底层的自由相机位置更新和旋转这个词没有半点关系。这里有个特别容易走错的岔路看到 API 里有rotateTo、setBearing直觉上会认为这不就是旋转吗。不是。bearing控制的是地图绕屏幕视线的旋转在球体上的表现是整个地球绕着你正对的那个点打滚看起来像地球侧翻着滚完全没有行星自转的味道。真正的自转只动经度pitch 和 bearing 基本保持恒定。记住这条球体自转 改 center 的 lng不是改 bearing。把这两个搞混你会花两小时调一个永远调不对的角度。另一层误解是纬度。lat在自转过程中必须固定住否则相机一边绕经度跑一边上下漂移观感会像镜头在球面上打滑。初值建议放在中纬度区间让陆地和水体的分布更均衡视觉信息量也更足别一上来正对两极——极地视角下球面被拉伸得很厉害转起来容易看出投影畸变。1.2 三种实现路径的取舍我为什么最终选了 setCenter 逐帧推进社区里能见到的写法大致三类各自适用的场景差别很大我先把对比摆出来。方案实现方式优点硬伤适用场景逐帧setCenterrequestAnimationFrame里推进经度后调setCenter速度绝对均匀、可精确控制、随时能停每帧触发一次重绘低端机有掉帧风险首屏展示、Hero 区、落地页链式easeTo每次moveend里再发一段easeTo代码短、自带缓动、和地图内建动画同一套调度每段动画头尾都有加减速长时间看像在一顿一顿地喘气短时演示、截图录屏FreeCameraOptions直接设置相机位置与朝向最贴近真实相机模型可同时控制俯仰与方位API 偏底层经纬度要换算成墨卡托坐标和地图自身相机状态容易互相覆盖需要复杂镜头运动、要做轨道环绕链式easeTo那个喘气问题值得多说一句。你写easeTo({center: [lng 90, lat], duration: 15000})默认缓动是 ease-in-out所以每 90 度都会先加速再减速肉眼非常明显。解决办法是传线性缓动easing: (t) t然后在这段动画结束的瞬间紧接着发下一段。即便这样两段动画之间仍然有一次moveend的事件往返和状态重建在低帧率设备上会看到极轻微的顿挫。想彻底消除只能回到逐帧推进。FreeCameraOptions我在做一条从太空俯冲到城市的镜头时才用。它的好处是相机位置和朝向是解耦的可以做出真实摄像机才能做的运镜坏处是你得自己维护一份墨卡托坐标而且一旦有别的代码比如flyTo动了标准相机两套状态就会打架。做单纯的地球自转用它的收益远小于成本。1.3 动手前的三项核对能省掉一半莫名其妙的报错第一项是版本。球体投影在不同大版本里的成熟度差异很大早期版本里它还属于实验特性行为和现在不完全一致。上来先console.log(mapboxgl.version)打出版本号再去对一遍当前版本的投影文档别拿着旧版本的写法去套新 API。构造函数里传projection: { name: globe }和运行时调map.setProjection({ name: globe })两种写法我都用过前者更省事后者适合做投影切换的交互。第二项是样式。globe 对底图样式是有要求的尤其是想同时叠地形的时候。我一般先用一个确定能跑的矢量样式把自转逻辑跑通再换成客户要的那套自定义样式。顺序反过来一旦出问题你分不清是投影的问题还是样式的问题。第三项是加载时机。所有跟投影、雾效、图层相关的操作全部塞进map.on(load)回调里。在样式还没加载完的时候调setProjection或者setFog行为取决于版本有的静默失败有的直接抛错排查起来很浪费时间。mapboxgl.accessToken YOUR_ACCESS_TOKEN; const map new mapboxgl.Map({ container: map, style: mapbox://styles/mapbox/satellite-streets-v12, center: [104, 26], zoom: 1.4, pitch: 0, bearing: 0, maxPitch: 30, projection: { name: globe } }); map.on(load, () { console.log(projection , map.getProjection()); });map.getProjection()这行日志别省。我曾经因为样式里写了别的东西把投影覆盖回平面自转代码跑了半天只看到地图在平移最后就是靠这行日志定位的。2. 自转内核用时间戳差分驱动经度累加2.1 每帧固定加 0.1 度是我踩过的第一个坑最直觉的写法是这样function loop() { lng 0.1; map.setCenter([lng, lat]); requestAnimationFrame(loop); }。本地跑很顺发到测试机上同事说怎么转得比我这快一倍。原因很简单requestAnimationFrame的回调频率跟着屏幕刷新率走。60Hz 屏每秒 60 次120Hz 屏每秒 120 次同样加 0.1 度速度直接翻倍。再加上掉帧的时候帧数变少地球又会变慢。也就是说这种写法让自转速度变成了一个由设备决定的随机量。正确做法是把时间当唯一自变量记下上一帧的时间戳算出这一帧的真实间隔秒用每秒多少度乘以间隔得到本次应该推进的角度。这样无论 30 帧还是 120 帧一圈转多久都是固定的。const dt Math.min((ts - lastTs) / 1000, 0.1); // 秒且封顶 0.1 lng (lng degPerSec * dt 540) % 360 - 180;那个Math.min(..., 0.1)是保险丝。切标签页、系统休眠、断点调试都会让两帧之间隔上几秒甚至几分钟不封顶的话回来第一帧地球就会唰地窜出去大半圈。封顶 0.1 秒意味着单帧最多推进degPerSec * 0.1度视觉上完全无感。2.2 经度回绕别拿 getCenter 的返回值做累加这是第二个坑而且很隐蔽。map.getCenter()返回的经度是归一化过的落在 [-180, 180) 区间。如果你写成map.setCenter([map.getCenter().lng delta, lat])跑到 180 之后它会跳回 -180虽然地图本身会正确处理但你的累加器就此断裂速度表上看不出问题日志里却会出现一段诡异的回跳。我的做法是自己维护一份lng变量只在两处和地图同步初始化时从map.getCenter()取一次用户在暂停后恢复自转时再取一次。中间所有帧都用本地变量算不回读地图状态。回读还有个额外代价——getCenter()内部要做投影反算每帧调一次属于白扔性能。归一化用这个式子lng (lng delta 540) % 360 - 180;加 540 是为了对付 JS 的负数取模。JS 里-10 % 360得到-10而不是350如果只写(lng delta 180) % 360 - 180在某些负值边界上会算错。加 540 之后先保证是正数再减 180任何输入都能落到 [-180, 180)。2.3 完整可跑的内核与参数标定下面这套是我目前默认的模板直接换 token 和容器 id 就能跑。const SPIN { degPerSec: 6, // 每秒推进多少经度 minFrameMs: 1000 / 45, // 提交重绘的最小间隔约 45fps maxDt: 0.1, // 单帧时间上限防瞬移 zoomRange: [0, 3.2], // 超出这个缩放区间就暂停自转 resumeDelay: 1500 // 用户松手后多久恢复 }; let rafId null; let lastTs 0; let lastCommit 0; let lng 104; let lat 26; let paused true; let resumeTimer null; function frame(ts) { rafId requestAnimationFrame(frame); if (paused) { lastTs ts; return; } // 帧率节流不到最小间隔就不提交 if (ts - lastCommit SPIN.minFrameMs) return; const dt lastTs ? Math.min((ts - lastTs) / 1000, SPIN.maxDt) : 0; lastTs ts; lastCommit ts; const zoom map.getZoom(); if (zoom SPIN.zoomRange[0] || zoom SPIN.zoomRange[1]) return; lng (lng SPIN.degPerSec * dt 540) % 360 - 180; map.setCenter([lng, lat]); } function pauseSpin() { paused true; clearTimeout(resumeTimer); } function resumeSpin(delay SPIN.resumeDelay) { clearTimeout(resumeTimer); resumeTimer setTimeout(() { const c map.getCenter(); lng c.lng; lat c.lat; lastTs 0; paused false; }, delay); } map.on(load, () { paused false; rafId requestAnimationFrame(frame); });速度怎么定一圈 360 度除一下就知道degPerSec 6是 60 秒一圈8是 45 秒一圈3是两分钟一圈。纯展示的首屏我一般在 5 到 8 之间选低于 3 会让人怀疑是不是卡住了高于 12 就有眩晕感尤其是球面上那些高对比度的海岸线在大幅移动的时候。纬度的初值我习惯取中纬度偏北理由在前面提过——大陆分布更均匀转起来画面信息量足。这个值在整个自转期间不要变只在恢复自转时从地图同步一次。节流的阈值 45fps 是试出来的。地球自转是匀速运动30fps 就能看出轻微的抖动60fps 又浪费性能45fps 在这个场景下是肉眼几乎分辨不出的平衡点。这个数字对不同项目可以调但建议不要低于 24低于 24 之后匀速运动会明显变得一顿一顿。3. 用户一动手自转必须让位3.1 用 movestart 判断用户开始操作是个陷阱我最早的版本是这么写的map.on(movestart, pauseSpin)map.on(moveend, resumeSpin)。想法很合理——用户一动就停不动了就恢复。跑起来之后地球在疯狂抽搐。根因是setCenter本身就是一次相机移动它同样会派发movestart、move、moveend。也就是说自转循环每推一帧就在自己身上触发一次用户开始操作于是暂停下一次moveend又恢复再下一帧又暂停。整个系统在自我否定里振荡。有的版本提供了类似不发 move 起始事件的内部开关但这类参数在不同版本之间的命名和行为并不稳定依赖它不是一个好工程决策。更稳的思路是判断用户意图不要看地图事件看原始输入事件。手指按下、鼠标按下、滚轮滚动、双指捏合这些是真正的用户意图信号而且不会被程序化的相机移动伪造。3.2 绑定位置、恢复延时与恢复前的状态重同步绑定的位置非常讲究这里有两个细节第一按下的事件绑在 canvas 上松开的事件绑在 window 上。因为用户很可能在画布里按下、拖到画布外面再松手只绑 canvas 会漏掉pointerup导致自转永远停在那里。第二wheel用地图的wheel事件而不是 DOM 的wheel事件。地图的wheel事件是 Mapbox 内部处理完缩放之后派发的它已经帮你判断了这次滚动是否真的改变了缩放省得你自己去猜阈值。const canvas map.getCanvas(); canvas.addEventListener(pointerdown, pauseSpin, { passive: true }); window.addEventListener(pointerup, () resumeSpin(), { passive: true }); window.addEventListener(pointercancel, () resumeSpin(600), { passive: true }); map.on(wheel, () { pauseSpin(); resumeSpin(2000); }); map.on(dragend, () resumeSpin());resumeDelay这个延时不是为了优雅是为了实用。用户松手后往往还在看刚拖到的位置如果立刻恢复自转他会觉得我根本停不下来。1500ms 是我反复调后的默认值短于 1000ms 有明显被抢的感觉长于 2500ms 又像功能坏了。滚轮给 2000ms因为滚动缩放通常是一串连续动作用户很可能滚完停一下再滚。恢复前那三行重同步代码别删const c map.getCenter(); lng c.lng; lat c.lat; lastTs 0;用户在暂停期间可能把地图拖到了完全不同的经度、甚至改了纬度。不同步直接恢复地球会啪地跳回上次的位置非常突兀。lastTs 0则是让恢复后的第一帧 dt 归零避免把暂停这段时间算进去。3.3 移动端事件顺序passive、pointercancel 和长按移动端的情况比桌面复杂踩过的具体问题有这么几个。一是老代码里用touchstart和touchmove很容易撞上浏览器的被动监听默认值事件回调里做任何阻塞动作都会被警告甚至直接失效。统一换成pointerdown/pointerup/pointercancel之后桌面和移动走同一套逻辑代码量直接砍掉三分之一。二是双指缩放。两个手指按下会派发两次pointerdownpauseSpin被调两次没关系函数内部幂等但两个手指抬起时pointerup也是两次resumeSpin会被调用两次。因为里面第一行就clearTimeout所以最终只保留最后一个定时器行为是对的。三是pointercancel。用户按住画布往上滑触发页面滚动浏览器会取消这个 pointer此时pointerup不会来。如果不处理pointercancel自转就永久停住了。这个坑我在一个移动端落地页上遇到过表现是滑一下页面再回来地球就不转了查了很久。四是长按。长按在部分浏览器里会触发文本选择或系统菜单如果画布上层有文字元素用户按下去可能触发的是选择而不是拖拽。给容器加user-select: none和-webkit-touch-callout: none能规避掉一大半。4. 后台标签页、掉帧与省电让自转在恶劣环境下别出丑4.1 切标签页回来地球瞬移的完整成因浏览器在标签页不可见时会把requestAnimationFrame挂起这本来是好事——省电。问题出在恢复的瞬间rAF重新开始调度第一帧的时间戳和你上一次记录的lastTs差了可能几分钟。如果你没做封顶dt 300秒degPerSec 6这一帧直接推进 1800 度也就是五圈。用户看到的是地球像被抽了一鞭子似的转飞出去。有人以为这是渲染 bug其实是自己的时间算术没兜住。两层防护都要做。第一层就是前面那个Math.min(dt, 0.1)保证单帧最多推进 0.6 度。第二层是显式监听可见性变化在页面隐藏时干脆把循环停掉回来时重置时间基准再重启document.addEventListener(visibilitychange, () { if (document.hidden) { cancelAnimationFrame(rafId); rafId null; } else if (rafId null) { lastTs 0; lastCommit 0; rafId requestAnimationFrame(frame); } });rafId null这个判断是防止重入。在某些浏览器上visibilitychange可能连续触发两次不判断的话会起两个循环速度直接翻倍。这个双循环问题是自转类需求里最高频的故障第 5.3 节还会遇到它一次。4.2 帧率节流到底省了什么一次粗糙但有效的实测我拿一台中低端安卓机做过对比同一套卫星底图 球体投影 约 40 个符号图层只改提交频率提交频率平均帧间隔主观观感发热与耗电每帧都提交≈60fps16.7ms顺滑两三分钟后明显温热45fps 上限22ms顺滑几乎看不出差别温热出现得慢一些30fps 上限33ms匀速运动有轻微顿挫明显更凉24fps 上限41ms能看出一格格走凉结论很明确45fps 是性价比拐点。再往上加人眼在这个运动速度下已经分辨不出纯粹是烧电。顺便说一个诊断技巧。想知道自转本身占了多少开销在frame里收集dt跑十秒后算个平均和最大值const samples []; // 在 frame 里 samples.push(dt * 1000); if (samples.length 300) { const avg samples.reduce((a, b) a b, 0) / samples.length; console.log(avg frame, avg.toFixed(1), max, Math.max(...samples).toFixed(1)); samples.length 0; }如果平均值稳定在 20 出头但最大值频繁冲到 80 以上说明不是自转本身重而是别的东西在周期性卡顿——常见的是数据源刷新、图层重新计算布局、或者页面上有别的动画在抢主线程。4.3 尊重减少动态效果的系统偏好这条容易被忽略但对可访问性很重要。系统层面开启了减少动态效果的用户通常是因为对运动敏感一个持续旋转的地球对他们来说是明确的不适源。const mq window.matchMedia((prefers-reduced-motion: reduce)); if (mq.matches) { // 不启动自转保留静态地球 } else { map.on(load, () { paused false; rafId requestAnimationFrame(frame); }); } mq.addEventListener(change, (e) { if (e.matches) { pauseSpin(); cancelAnimationFrame(rafId); rafId null; } else { lastTs 0; lastCommit 0; rafId requestAnimationFrame(frame); paused false; } });注意change里也要处理双循环如果rafId已经不为 null 就不要再起一个。这个场景在用户手动切换系统设置时才会触发测起来麻烦但真出了就是速度异常很难和别的原因区分。另外我还加了一个兜底首屏启动后的三秒内如果平均帧间隔超过 40ms就把degPerSec降一档或者直接停转。低端设备上转不动比不转更糟掉帧的自转看起来像坏了。5. 观感调优让它像行星而不是像失控的转盘5.1 俯仰角、缩放区间与速度必须联动单独调速度是不够的。这三个参数是一套的。pitch我一般给 0 或者很小的角度5 到 10 度。pitch 一旦拉到 30 度以上自转过程中球体的透视变化会很强烈看起来不像自转像镜头在绕着球体打转。同时把maxPitch限制在 30 以内防止用户自己拉高之后自转观感崩掉。zoomRange决定了什么时候该停。缩到很小的时候球体是个小圆点转得再快也没信息量放大到城市级别球面几乎是平的再自转就是纯粹的平移而且移动速度在屏幕上的像素速度会非常快看久了晕。我默认给的区间是 0 到 3.2超过 3.2 就暂停自转缩回去再恢复。这个判断放在frame里每帧比一次getZoom()开销可以忽略。还有一个交互开关如果这个地球纯粹是装饰把dragRotate关掉避免用户不小心用右键拖出倾斜视角。如果要做成可探索的就保留但记得在pitch被用户改过之后恢复自转时把 pitch 也一起同步回一个合理值否则镜头会歪着转。5.2 大气、星空和深色底图贡献的行星感纯白底图上的球体怎么看都像一颗塑料球。真正让它像行星的是球体边缘那层薄薄的大气光晕和背景里若隐若现的星空。这两样都是靠雾效配置出来的map.on(load, () { map.setFog({ space-color: #0b0f1a, star-intensity: 0.6, high-color: #1b2a4a, horizon-blend: 0.08 }); });space-color是球体之外的那片太空的颜色star-intensity控制星点密度high-color是大气的上层颜色horizon-blend控制地平线附近混合带的宽度——调大一点边缘会更柔和调小会更硬像一颗没有大气的天体。底图风格我用卫星或者深色矢量都比浅色好。浅色底图在球体边缘的对比度太低大气光晕根本看不出来。另外底图里如果有大面积的亮色标注文字自转时这些文字会围着球面绕圈跑观感非常吵记得在展示态把标注图层关掉。setFog和球体投影是有绑定关系的如果投影被切回平面雾效会变成另一种表现近地雾效果完全不同。这也是为什么第 1.3 节强调要先确认投影状态。5.3 组件框架里封装清理、StrictMode 和速度翻倍把上面这套塞进 React 的useEffect时有两个具体的坑。第一个是清理。cancelAnimationFrame必须在 cleanup 里调而且rafId要能拿到最新值。用useRef存不要用普通变量否则闭包捕获的是旧值。第二个更阴险开发模式下某些框架会刻意把组件的挂载→卸载→再挂载跑一遍用来暴露副作用清理问题。如果你的 cleanup 没写或者写了但没真正取消就会出现两个自转循环同时推进同一个地图速度精确翻倍。我见过有同事把这个当成不同设备性能差异查了半天最后发现只有开发模式快一倍生产环境正常。useEffect(() { const ref { raf: null, timer: null, paused: true, lng: 104, lat: 26, lastTs: 0, lastCommit: 0 }; const frame (ts) { ref.raf requestAnimationFrame(frame); if (ref.paused) { ref.lastTs ts; return; } if (ts - ref.lastCommit 1000 / 45) return; const dt ref.lastTs ? Math.min((ts - ref.lastTs) / 1000, 0.1) : 0; ref.lastTs ts; ref.lastCommit ts; ref.lng (ref.lng 6 * dt 540) % 360 - 180; mapRef.current.setCenter([ref.lng, ref.lat]); }; ref.raf requestAnimationFrame(frame); return () { cancelAnimationFrame(ref.raf); clearTimeout(ref.timer); }; }, []);关键点在于把所有可变状态塞进一个 effect 内部的对象里而不是散在组件作用域。这样每次 effect 重新执行都是全新的状态不会残留上一次的定时器和帧 ID。Vue 那边同理用onBeforeUnmount取消。我还习惯加一行防御在启动前检查一下地图的容器是否还在 DOM 里。单页应用里快速切路由时地图实例可能已经被销毁但 effect 还在跑这时候setCenter会抛错。6. 症状对照表与一次完整的排查链路6.1 症状速查现象最可能的根因处理地球疯狂抽搐、一顿一顿用movestart判断用户操作被自身setCenter触发改用pointerdown/wheel等原始输入事件切标签页回来瞬移半圈dt没封顶Math.min(dt, 0.1)visibilitychange重置开发环境快一倍生产正常组件双挂载两个 rAF 循环cleanup 里cancelAnimationFrame拖拽结束后自转恢复但地球跳回原位恢复前没从getCenter()同步恢复时重读 center拖拽时地图抖动、拖不动暂停信号没生效setCenter与拖拽抢相机检查事件是否被上层 DOM 拦截自转速度在不同设备上不一致每帧加固定角度而非按时间差分改成时间戳差分地球转到某处突然卡住不转缩放超出zoomRange检查getZoom()或放宽区间移动端滑一下页面后永久停转pointercancel未处理补pointercancel监听自转时球面边缘很脏、有亮线雾效和底图风格不匹配调horizon-blend、换深色底图6.2 一次拖拽打架的完整排查记录最后讲一个我实际遇到的、折腾最久的案例把排查链路完整走一遍因为它的思路可以复用到很多地方。现象地球自转一切正常但用户按住地图拖拽的时候画面会高频抖动像是拖拽和自转在互相抢方向盘。松手后恢复正常。第一步先确认自转在拖拽期间到底停没停。我在frame的提交分支里加了一行日志打时间戳和当前paused值。结果很清楚拖拽期间日志还在刷说明pauseSpin根本没被调用。第二步确认pointerdown到底有没有绑上。在pauseSpin开头加了一个计数器然后在页面上按住地图计数器纹丝不动。到这里就锁定了方向——不是逻辑问题是事件没到。第三步查事件去哪了。用document.addEventListener(pointerdown, e console.log(e.target), true)在捕获阶段打日志发现e.target不是地图的 canvas而是一个盖在上面的半透明遮罩 div。那个 div 是后来做加载完成前的骨架屏时加上去的动画结束后opacity设为 0 但没有pointer-events: none所以它一直趴在最上层吃掉所有指针事件。第四步验证这个判断。临时把那层 div 的pointer-events改成none拖拽抖动立刻消失。根因确认。第五步正式修复。两件事给遮罩层加pointer-events: none同时把暂停的绑定从 canvas 提到地图容器的捕获阶段作为额外保险——即使以后再有人往上叠东西只要事件还在这棵子树里我都能先一步收到。const container document.getElementById(map); container.addEventListener(pointerdown, pauseSpin, { capture: true, passive: true });这个案例的教训是相机类的异常先分清是逻辑在抢还是事件没到。两者的现象很像——都是画面不受控——但排查方向完全相反。逻辑在抢就去查暂停条件事件没到就去查 DOM 层级和pointer-events。我后来把这个判断固化成了习惯任何交互异常第一件事是在捕获阶段打一次e.target日志三秒钟就能定方向。另一个容易忽略的同类问题如果你用一个透明的地图容器做点击穿透布局容器本身没有尺寸或者被绝对定位到别处地图的 canvas 会拿到宽高为 0 的渲染尺寸表现是地图不显示但自转代码在跑控制台还有一堆 resize 警告。这种情况查 DOM 尺寸比查代码快。我个人在实际操作中的体会是地球自转这类看起来很轻的需求八成的返工都来自三个地方把自转当成一个配置项、用地图事件判断用户意图、以及忘了浏览器会挂起后台页面的计时器。这三条守住剩下的就是调参——速度、纬度锚点、恢复延时、缩放区间四个数字反复试几遍就能找到舒服的组合。至于那几个数字的具体取值其实没有标准答案跟你的底图配色、球体在页面里占多大、用户是扫一眼还是停下来看都有关系。我的建议是先把速度调到你盯着看十秒不心烦再往下调一档通常就是对的。
