从 3D 到 2D:足迹地球的地图渲染迁移之路
从 3D 到 2D:足迹地球的地图渲染迁移之路
背景:为什么要做「足迹地球」
LifeOS 是一个 AI 原生的个人工作台,其中有一个「足迹地球」模块——用户可以在 3D 地球上标注去过的地方(含照片、笔记、日期),并通过「省 → 市」两级下钻,像高德足迹一样回顾自己的足迹版图。
这个模块的需求核心是足迹式交互:全国视图不显示标注,进入具体省份后才显示该省的标注,进入城市后进一步筛选。这是高德地图「足迹」的经典交互范式。
v1.0:globe.gl 3D 球体方案
技术选型
最初选择了 globe.gl 2.46.1(基于 three.js 的 3D 地球库),原因:
- 轻量、API 友好
- 支持 GeoJSON polygons + HTML 元素定位
- 3D 地球的视觉冲击力强
技术栈:Next.js 16 + TypeScript + Tailwind CSS v4 + PostgreSQL + Prisma ORM v7。
v1.0 实现了什么
M1-M5 里程碑全部交付:
- 3D 地球拖拽旋转、悬停高亮、点击下钻(省 → 市)
- 标注点(HTML 气泡)绑定照片/笔记
- 高德足迹式交互:全国视图无标注,进入省份后才显示
- 标注 CRUD + 图片上传
v1.0 遗留的问题
上线后暴露了三类问题:
1. 交互范式不符
3D 球面投影和 2D 平面地图的操作体验完全不同。自动化测试点击省份极不稳定——球体旋转/投影误差导致同一坐标点击不同次可能进不同省。
2. 性能开销
three.js bundle ~900KB,对 2C2G 的服务器压力很大。HTML 元素 3D 投影在标注超过 50 个时就开始卡顿。
3. 添加标注繁琐
需要手动查经纬度、手动填省/市,用户体验差。
v2.0:迁移到 MapLibre
为什么选 MapLibre
对比了 globe.gl(3D)和 MapLibre GL JS(2D):
| 维度 | globe.gl (3D) | MapLibre (2D) |
|---|---|---|
| Bundle | ~900KB | ~150KB |
| 标注性能 | 50 个卡顿 | 500 个流畅 |
| 下钻动画 | 相机飞行计算量大 | flyTo 原生丝滑 |
| 高德相似度 | 低(球面 vs 平面) | 高 |
| 内存占用 | 300-500MB | 80-150MB |
核心结论:足迹地图是 2D 操作,不是 3D 展示。MapLibre 的平面地图视角和高德的交互范式高度一致。
迁移过程中踩的坑
坑 1:MapLibre 6.x ESM-only 与 Turbopack 不兼容
地图初始化成功(canvas 存在)但 style 永不加载、零 console 日志——排查极其困难。
原因:maplibre-gl@6.x 是纯 ESM 包,Next.js 16 Turbopack 处理异常。
解决:降级到 maplibre-gl@5.24.0(CJS+ESM 双格式),立即可用。
教训:新大版本库先验证与构建工具的兼容性。ESM-only 的库在 Next/Turbopack 里是高危信号。
坑 2:map.on("load") 依赖底图瓦片就绪
底图瓦片加载超时(CartoDB 国外 CDN),load 事件永不触发 → 省图层从未添加。
解决:移除外部底图(纯深色背景 + 本地 GeoJSON),改用 style.load 双监听。
教训:地图类库的 load 事件语义要弄清楚——style.load 是样式就绪,load 可能等瓦片。国内网络慎用国外瓦片 CDN。
坑 3:DataV 海外 IP 返回 403 → 地球纯黑
生产环境(Cloudflare 后面)地球纯黑,但本机/服务器 curl 正常。定位到”海外 IP”变量——Cloudflare 边缘节点(海外 IP)请求 DataV 的 OSS 被 403。
解决:本地打包 35 个 GeoJSON(全国 + 34 省)到 public/geojson/,加载链改为本地优先 + 服务器代理 + DataV 兜底三级回退。
教训:国内数据源 + 海外 CDN = 必踩地域限制坑。自托管/本地化是最稳方案。
坑 4:MapLibre 字符串化 properties
点击地市后表单经纬度没自动填充。原因是 MapLibre GeoJSON source 会把非标量 properties 序列化成字符串——"center": "[112.98,28.19]" 变成了字符串。
解决:JSON.parse 解析字符串恢复数组。
教训:MapLibre 的 properties 只保证标量可靠,数组/对象会被字符串化。
坑 5:Source “cities” already exists → 地图空白
快速切换省/市时偶发。根因是 useEffect 重跑导致并发 addSource。
解决(三重防护):in-flight 防重 + 防御性移除 + 竞态校验。
教训:useEffect + 异步加载 = 必须防竞态。
三个新功能的实现
需求 1:点击地市弹表单 + 自动关联经纬度
点击地市后,自动填充省/市/经纬度到表单,无需手动查询。省视图下点击具体地市,表单弹出且全自动填充——名称、省、市、纬度、经度一步到位。
需求 2:日期选择组件
日历选择 + 手动输入混合——日历图标弹出 Popover + Calendar 组件(中文 locale),旁边保留手动输入框,可自由输入或微调。
需求 3:无 noteId 时自动生成笔记
保存标注时,如果未关联笔记,系统自动创建一篇「足迹」笔记并关联——内容包含地点、日期、描述,自动写入 足迹/{名称}.md。
验证与部署
验证结果
本地测试(dev server + playwright)+ 生产验证(www.yxgzos.cloud)全部通过:
- MapLibre 省份边界渲染清晰 ✅
- 点击地市弹表单 + 自动填充 ✅
- 日期选择组件正常 ✅
- 自动生成笔记正常 ✅
- 全国/省视图标注显隐正确 ✅
部署
沿用安全部署脚本:备份 → 解压(不删 node_modules)→ 依赖判断(无新依赖跳过 npm ci)→ prisma generate → pm2 restart。本次无新依赖,未触发 npm ci,避免 2 小时重装中断服务。
经验总结
- 交互范式决定技术选型:足迹地图(2D 操作)用 MapLibre,地球仪(3D 展示)才用 globe.gl
- 选型前先确认交互范式——“地球仪” vs “足迹地图”是完全不同的交互模型
- 国内项目慎用国外 CDN:底图瓦片、数据源都要考虑地域可达性
- 外部数据源要本地化/代理化:能打包就打包,不能打包就服务器代理,绝不裸连
- 新库大版本先验证兼容性:ESM-only 库在 Next/Turbopack 是高危
- useEffect + 异步加载必须防竞态:in-flight 防重 + 视图校验 + 防御性移除,三层缺一不可
迁移从 3D 到 2D,bundle 从 900KB 降到 150KB,标注性能从 50 个卡顿提升到 500 个流畅。地图渲染的核心教训是:展示用 3D,操作用 2D——选错了交互范式,后面全是坑。