企业官网建设流程全解析

第一次接到"首屏放一个会自转的地球"这个需求，我的判断是三分钟收工：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 逐帧推进

社区里能见到的写法大致三类，各自适用的场景差别很大，我先把对比摆出来。

链式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之后，桌面和移动走同一套逻辑，代码量直接砍掉三分之一。

二是双指缩放。两个手指按下会派发两次pointerdown，pauseSpin被调两次没关系（函数内部幂等），但两个手指抬起时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 个符号图层，只改提交频率：

结论很明确：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 症状速查

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 尺寸比查代码快。

我个人在实际操作中的体会是，地球自转这类"看起来很轻"的需求，八成的返工都来自三个地方：把自转当成一个配置项、用地图事件判断用户意图、以及忘了浏览器会挂起后台页面的计时器。这三条守住，剩下的就是调参——速度、纬度锚点、恢复延时、缩放区间，四个数字反复试几遍就能找到舒服的组合。至于那几个数字的具体取值，其实没有标准答案，跟你的底图配色、球体在页面里占多大、用户是扫一眼还是停下来看，都有关系。我的建议是先把速度调到你盯着看十秒不心烦，再往下调一档，通常就是对的。