前阵子整理手机里的地图收藏夹发现一个尴尬的事实我收藏了两百多个地点但真正要用的时候一个也想不起来。它们分散在不同地图应用、聊天记录和截图里分类只有“想去”和“收藏”两种状态至于“为什么想去”“和谁一起去”“大概预算多少”这些信息全都丢在记忆深处。于是我用周末时间写了 lingbot-map——一个 Web 端轻量地图打点与整理工具把散落的地址、路线和备注整理成清晰可用的地图。这个项目很适合喜欢自驾、探店、自由行的人也适合想练手地图应用开发的前端同学。如果你也有“收藏一大堆地点却从来不会回看”的毛病这篇文章应该能给你一些直接能用的思路。1. 痛点复盘收藏了一百个地点到了现场一个也想不起来1.1 现有工具的三种“收藏失效”场景先说我把问题暴露出来的三个场景它们基本上覆盖了大多数人收藏地点的失效方式。第一种是收藏动作太轻信息记不住。我在一个美食应用里看到一家面馆很想去点一下“收藏”然后就再也没有然后了。等我真正路过那条街时我根本想不起这家店叫什么只记得“有家面馆好像不错”。但收藏列表里几百家店关键词翻了半天最后放弃随便找了一家。这种失效的本质是收藏只保存了一个地点名称没有保存“我为什么收藏它”。缺少了动机信息地点就是一堆符号大脑无法有效提取。第二种是跨应用的信息相互隔离。这个月用应用 A 做攻略下个月又迁移到应用 B再往后可能是朋友在微信里扔过来一个定位。等到出发前想统一查看时需要同时打开四五个应用来回切换。最崩溃的是不同应用对地点名称的格式还不一样同一个地方能出现“老王烧烤”“老王烧烤总店”“老王家烧烤店”三种写法光靠眼睛去重就想摔手机。第三种是分享给别人非常困难。你想把一个三日游路线发给朋友传统方法是逐条截图配上大段文字说明最后朋友回一句“太多了看不过来”。地图应用自带的“发送路线”功能通常要求对方也安装同一个应用而且数据打包后很难二次编辑。换句话说现有的工具在处理“个人地点资料的整理与沉淀”这件事上本质上没有做对。1.2 lingbot-map 的产品边界不做导航只做整理引擎在做 lingbot-map 之前我先问了自己一个问题它到底是做什么的如果答案只是“一个能放标记点的地图”那市面上已经有一堆了没必要再做一个。真正值得做的是“地点信息的结构化整理”。导航交给专业导航软件社交分享交给聊天工具lingbot-map 要承接的是中间那段把一坨乱麻的地点信息变成一份干净、可编辑、可导入导出、能长期积累的数据资产。打个比方地图应用自带收藏功能像一个杂货抽屉东西能塞进去但很难翻找lingbot-map 则像一个分好类贴好标签的文件柜每个地点都有编号、位置、备注、标签而且整个文件柜可以打包搬走。所以它的产品边界从一开始就很明确允许用户以多种方式快速添加地点编辑地点的属性把多个地点串联成路线最后以通用格式导出给别人。所有功能都围绕“整理”服务不去做逐向导航不做实时路况不做社交信息流。这个边界帮我砍掉了很多没必要的复杂度也让项目在一开始就有了清晰的架构方向。2. 数据模型先行先设计字段再画界面2.1 一个标记点最少需要哪 10 个字段很多人在做地图类项目时会先选地图引擎、先画 UI等做了一半才发现“地点信息不知道该存哪些字段”。我在 lingbot-map 里反着来先花一晚上设计数据模型再动界面。这个顺序省了我后面至少两周的返工时间。一个标记点最终确定的字段如下表字段类型用途说明idstring唯一标识写死了不可变用来关联路线和导出数据namestring地点名称用于列表展示和搜索latitude / longitudenumber经纬度采用 WGS-84 标准所有图源叠加问题时统一转换categorystring分类如美食、住宿、机位、露营地用于图表筛选notestring自由文本备注用来记录“为什么收藏它”tagsstring[]标签列表支持一对多描述如“小众”“夜景”“要预约”photosstring[]图片链接数组只存外链不存二进制数据ratingnumber个人评分 0-5用于后期筛选和排序visit_statusenum想去 / 已去 / 已放弃方便做行前筛选create_timedatetime创建时间用于排序和统计这个表用起来之后我才发现note 字段才是整个系统的灵魂。以前在地图应用里收藏只能看到一个名字加一个地址现在每次收藏时顺手写一句话比如“周三中午开门招牌是花椒鸡人均 80靠窗位置下午光线好”过两个月再翻出来当时的判断全在不需要重新回忆。rating 和 visit_status 则负责做减法已筛选出不想去的地点它们仍然留在数据库里但不再出现在默认视图这个历史数据以后做统计时很有价值。2.2 数据交换格式选择 GeoJSON 的理由确定字段之后就是数据交换格式。我最开始想简单写一个 JSON把地图数据倒进去导出就行但仔细一想这个 JSON 将来要想被其他地图工具直接打开标准支持会很麻烦。于是我换成了 GeoJSON而且是标准的 FeatureCollection 结构。GeoJSON 的好处在于它是地理信息领域的通用语言。地图组件认识它地理信息系统认识它很多笔记本软件也能识别它。一个标记点大致长这样{ type: FeatureCollection, features: [ { type: Feature, geometry: { type: Point, coordinates: [116.3912, 39.9072] }, properties: { id: a1b2c3, name: 某面馆, category: 美食, note: 招牌是花椒鸡周三中午开门, tags: [小众, 午餐], photos: [https://example.com/photo.jpg], rating: 4.5, visit_status: 想去, create_time: 2025-01-15T10:30:00Z } } ] }用 GeoJSON 导出之后我实测过多种地图工具都能直接导入同一个文件。反过来从外部获取 GeoJSON 数据时解析逻辑也非常简单遍历 features 数组把 properties 塞进自己的表格即可。对个人项目来说等于花最小的力气拿到最大的互操作性。将来想迁移数据或者让别人接你的数据几乎零成本。2.3 地点去重的匹配策略地点收藏多了去重是逃不掉的。第一版我直接按名称去重结果“某面馆”和“某面馆总店”被视为两个地点很惨。后来我采用了一个更实用的匹配策略名称相似度加坐标距离双条件。具体做法是新地点入库时先搜索经纬度 500 米范围内的已有地点如果存在记录再比较名称的相似度相似度高于一定阈值就提示“疑似重复”把两个点并排显示在界面上由用户决定是否合并。坐标条件用于排除不同城市同名店的误判名称条件用于避免相邻的两家不同店被强行合并。这个策略不完美但足够解决 90% 的重复情况。真正关键的启发是去重一定要放在数据写入之前做提示而不是等大量脏数据沉淀后再做清理。事后清理的麻烦程度是指数级上升的因为还得处理路线引用和历史归属关系。3. 界面与交互地图拖拽、列表滚动、详情卡片三者的协调3.1 地图与列表的联动逻辑地图类工具最容易做崩的地方就是“地图和列表吵架”。一开始我是地图放在左侧、列表放在右侧两边同屏显示。点击右侧列表某一项地图飞过去并打开弹窗拖动地图时右侧列表同步重排。听起来挺正常实际用起来特别累。地图一拖动列表就在那高频刷新视觉上像一直在抖动列表一滚动地图也跟着不停移动搞得我不知道自己在看哪里。后来我把联动逻辑理清成两条规则列表和地图以“点击”为唯一双向同步信号地图拖动时列表进入静默模式不刷新等用户松手停留超过 300 毫秒后再根据当前中心点附近有没有可见标记点来更新列表而不是每帧都重排。这个改动让整个应用的流畅度上了一个台阶。触发一次列表刷新只需要关心一个状态变化大大降低了计算量和调试难度。3.2 快速打点的三种方式打点是整个系统的高频操作如果效率提不上去用户很快就会失去继续使用工具的耐心。我在 lingbot-map 中设计了三种打点方式对应三种不同使用场景。第一种是搜索关键词后打点。输入框里敲“某面馆”请求公共地图搜索服务返回几个候选结果用户点一下候选条地点就算收集完成。这种方式的体验最接近日常使用习惯适合明确知道目标名称的情况不需要手动记坐标。第二种是长按地图打点。在地图上长按住某个位置会出现一个可拖动的标记松手后弹出编辑框然后发送一个逆地理编码请求把经纬度反向解析成可读的地址描述。这种方式特别适合“我路过一个地方觉得不错但不知道它叫什么名字”的场景。注意逆地理编码器延迟较高我会在 UI 上先显示坐标作为临时地址等返回结果后自动填充不让用户干等。第三种是批量 CSV 导入。如果你手上已经有整理好的地址表格比如从旅行攻略网站导出的清单一行一个地点包含名称、描述、分类直接上传 CSV 文件即可。CSV 解析有一个特别容易踩的坑——编码问题我用 UTF-8 强制编码读取并在导入后立刻回显解析结果用户能提前发现乱码或列错位避免数据悄悄掉进错误字段。3.3 移动端手册如何避免手势冲突移动端地图应用的交互痛点非常集中地图缩放、列表滚动、弹窗内部滚动三者共用同一块触摸屏。如果你不做特殊处理用户想滚动列表时地图跟着缩放想缩放地图时列表又疯狂滚动体验会非常糟糕。我的处理方案是“物理隔离”。列表和地图采用上下分层切换的方式默认状态下地图铺满全屏底部浮起一个窄条预览区用户点击底部按钮列表以抽屉形式从底部滑出此时地图区域只剩顶部四分之一。在这种布局下地图手势和列表手势一定不会发生在同一块视觉区域上从根本上解决了冲突。只是界面视觉上没有传统的“左边地图右边列表”那么气派但实际用起来非常稳。此外还有一个细节地图容器上的触摸事件默认是没有禁用的如果弹窗里有可以滚动的富文本内容用户操作时会发现整个页面跟着地图一起动。我在弹窗容器上设置了touch-action: manipulation明确告诉浏览器这里不允许双指缩放只允许滚动。这个一行 CSS 就解决的问题花了我整整一个下午排查。4. 技术选型与实现过程中的三次取舍4.1 地图引擎Leaflet 还是 MapLibre GL地图引擎是这个项目最核心的三方依赖选错了后面换起来会非常痛苦。我当时在两个候选之间犹豫了很久Leaflet 和 MapLibre GL。对比起来各有利弊。对比维度LeafletMapLibre GL体积更轻核心包只有几十 KB相对更大但包含 3D 能力样式系统基于 CSS 和简单图层配置自定义灵活基于 style specification强大多样插件生态非常丰富自定义 marker、聚类都有现成插件相对较少很多功能需要自己写WebGL 渲染不依赖 WebGL兼容性极好依赖 WebGL老设备上可能出现问题学习曲线平缓官方文档清晰偏陡样式规范需要额外学习lingbot-map 最终选了 Leaflet。核心原因是“够用”我的业务功能集中在点标记、弹窗、路线绘制和数据交互上并不需要炫酷的 3D 视觉也不需要对复杂矢量瓦片做精细控制。Leaflet 让数据层逻辑非常直观我可以在浏览器里快速定位是地图问题还是数据问题。另外它不依赖 WebGL在配置不算高的办公电脑和低端手机上表现都比较稳定。如果将来确实要做炫酷的动态轨迹展示再把地图引擎替换成 MapLibre GL底层的 GeoJSON 数据模型完全不需要改动这就是标准数据格式带来的迁移红利。4.2 状态管理为什么没有上 Pinia一个从零开始的个人项目很容易一上来就把状态管理库引入觉得“正规项目都应该有”。我在 lingbot-map 项目里一开始也差点加了 Pinia但后来发现业务规模其实撑不起这个复杂度。地点数据的核心状态只有当前地图中心点、当前选中的标记点、可见标记点列表、筛选条件。这些状态之间的派生关系非常清晰我用一个可组合函数把“地图实例”和“标记点列表”绑定在一起让数据更新适时触发地图刷新完全够用了。引入 Pinia 反而多了一层数据流每次新增功能都要在 store、视图、组件之间来回接线开发速度下降。这个取舍的参考标准很简单当你的共享状态不超过 6 个、且不存在多页面级复杂关联时能不引入就不用引入。除非后续做协作编辑功能多个用户实时操作同一张地图状态复杂度一下子上来了再引入状态管理库也不迟。代码里留好接口即可不需要提前投资。4.3 数据持久化localStorage 上限 5MB 的教训与 IndexedDB 方案数据持久化是另一个容易被低估的模块。第一版我用 localStorage 存地点列表当时觉得存几百个标记点没问题但实际使用中很快打脸地点数量达到一千个左右时如果每个点带备注和标签再加上路线数据很快就逼近甚至超过 5MB 的上限。更隐蔽的问题是localStorage 是同步阻塞式 API每次写入大 JSON 时页面会有明显卡顿。后来我把主力存储切到 IndexedDB用异步操作能存的数据量大了很多也不再卡主线程。操作逻辑用几个接口封装了一下读列表、加一笔、改一笔、批量导入、清空。IndexedDB 的学习成本确实比 localStorage 高一点但对自己掌握用户核心数据的产品来说这笔投入非常值得。另外我在导出功能里额外留了一个备份按钮把全部数据生成 GeoJSON 下载到本地即便本地数据库被浏览器清理策略误删也能一键恢复。5. 五个线上没炸、线下炸了的坑附排查过程5.1 坑一坐标偏移——栅格底图与 GPS 坐标玩“错位”lingbot-map 最早使用了一套看起来正常的栅格底图服务结果第一批测试数据进去后我发现打点位置怪怪的坐标明明来自 GPS 定位理论上是精确的但标记点在地图上显示的位置和真实位置差了几百米。一开始我怀疑浏览器的定位 API 出了问题专门写了一个只显示当前定位坐标的空白页面结果定位没问题又怀疑是标记点图标 anchor 偏移排除了最后把同一份 GeoJSON 数据放到另一个地图引擎里渲染位置正常。这下范围缩小到“地图图源用了偏移坐标系”而不是标准 WGS-84 坐标系。问题找到了解决思路也清晰了不要求所有图源都用标准坐标而是做一个转换适配层。底图加载时主动声明自身坐标系渲染标记点前调用一次坐标转换函数把 WGS-84 坐标临时转换为该图源所需的坐标内部数据库始终存标准坐标绝不在存储层做永久性转换。这个方案的边界很干净地图切换时只是渲染层变化数据永远不受影响。5.2 坑二上千个标记点把浏览器卡成幻灯片当地点数据超过一千个时Leaflet 默认的 DOM marker 渲染方式开始撑不住了。拖动地图时帧率掉到十几帧放大缩小有明显的迟滞感整个页面像在放慢动作。我用浏览器性能分析工具抓了一下发现主要时间花在 renderer 线程上——每一个 marker 都是一个 DOM 元素浏览器需要为上千个元素不断重排、重绘不卡才怪。解决方式分为两层。第一层用 Canvas 渲染替代 DOM marker 展示普通点地图拖动时由 Canvas 直接负责绘制性能提升非常明显第二层引入空间聚类当地图缩放到一定级别以下相邻几个点合并成一个“数量气泡”需要用户放大地图或点击气泡时才展开独立标记。这两招组合后四千个点的场景也能流畅操作。如果你也遇到同样问题建议先做聚类再看 Canvas因为聚类能直接减少需要渲染的点数量对低端设备更友好。5.3 坑三带照片的导出文件大得离谱一开始我设计 photos 字段时想着“把图片转成 Base64 塞进 JSON 吧这样导出文件能自包含用户拿到一个文件就能看完整内容”。第一次导出测试时我只添加了三十张照片生成的 GeoJSON 文件就超过了 800MB程序直接卡死。Base64 会把二进制体积扩大约 33%三十张手机照片少说也要几千兆这种方案纯粹是自找麻烦。我最后改成 photos 字段只存图片的远程 URL 或压缩缩略图外链导出文件里附带一个简易说明告诉用户图片没有内嵌需要联网才能查看。对于没有外链的本地照片我在程序里提供了一个配套的照片目录导出结构把廓清的图片按标记点 ID 命名后单独打包GeoJSON 里只填写相对路径。这样数据的完整性和文件的可携带性都保住了文件大小也回到了几 MB 的正常范围。5.4 坑四浏览器缓存清了三个月的数据全没localStorage 挂在浏览器环境下本身就意味着“数据随时可能被浏览器策略清掉”。有一次我清理浏览器缓存时不小心勾选了“清除站点数据”再打开 lingbot-map三个月整理的一千多个地点全部消失那一刻我后背都凉了。虽然我技术上知道 localStorage 不可靠但真的发生时还是觉得很崩溃。这次事故之后我做了三个补救措施一是把存储切到 IndexedDB降低被普通“清缓存”操作误伤的概率二是在每次关闭页面时自动生成一份数据快照保存到浏览器的下载目录三是在页面启动时检测数据文件是否存在如果不存在则弹出一个醒目的恢复引导让用户选择从本地备份导入。经历过这次数据丢失我才真正意识到对个人工具来说数据可恢复性比界面华丽重要一百倍。5.5 坑五手机上双指缩放失效移动端测试时我发现地图的双指缩放经常失灵表现为一点就跳动或者两指刚触到屏幕就缩放到最小级别。排查过程先把锅甩给 Leaflet查了 issue 列表发现是浏览器默认的触摸事件在作怪地图容器没有正确设置 touch-action 属性浏览器在处理双指手势时和多点触控库产生了冲突。除了 touch-action还有一个细节是页面根元素禁用了默认的的缩放行为但监听事件时使用了preventDefault()而且没有调用stopPropagation()导致事件冒泡到底图控制层被误判。最后统一规定全局不滥用 preventDefault只有明确需要拦截手势的元素才调用地图容器上固定写touch-action: none让地图引擎完整体接管手势。改完后双指缩放、单指拖动都恢复正常。这个问题排查起来真的很费时间但原因说出来就一行 CSS 和一则事件处理规范。6. 项目当前状态与我认为它还能做什么6.1 已跑通的功能清单lingbot-map 到目前为止已经是一个能稳定日常使用的工具常见操作都顺畅了地图浏览、搜索打点、长按打点、CSV 批量导入三种收藏方式地点属性编辑、分类标签管理、去重提示与合并路线绘制与排序支持把一批标记点按距离最近原则自动排列生成推荐行走顺序基于 GeoJSON 的一键导出和导入数据完全归用户所有移动端自适应布局离线静态资源缓存良好弱网环境下基础功能仍可用整套代码全部由我一个人维护没有后端服务器数据默认存在浏览器本地。这种架构的优点是可以零成本部署到任意静态托管平台劣势是协作功能完全没有——只要数据不共享它就只能算个人记事本。6.2 三个后续方向协作编辑、时空回放、兴趣点订阅如果未来继续深挖我认为有三个方向值得考虑。第一个是协作编辑。底座数据已经是 GeoJSON问题只在于实时同步和冲突处理。把数据模型搬到云数据库用类似协同文本编辑的处理方式处理地点字段合并就是一张可共享的旅行地图。第二个是时空回放。每个标记点都有创建时间如果把按时间顺序播放这些点被添加的过程再配合路线轨迹就能看到一次旅行决策的完整脉络。这个功能适合做行程总结类内容分享。第三个是兴趣点订阅。可以把某个人公开的 GeoJSON 当作数据源订阅后自动同步更新。比如某位旅行博主持续维护一份“小众机位地图”你订阅后每次打开都能看到最新版本不需要手动重复导入。这个模式把工具从“自己的剪贴簿”升级成了“内容生态”有意思也有挑战。6.3 给想复刻同类项目的人几点建议最后说几条非常实在的建议。第一个建议是数据字段一定在设计阶段一次想清楚。后期加字段容易迁移旧数据很痛尤其是历史上已经写入到了嵌套结构里要一层层拆出来。第二个建议是用通用格式 GeoJSON 作为导出格式不要自创私有结构否则你未来的迁移成本和别人接入的难度都会很高。第三个建议是地图引擎选熟不选新选轻不选重真实项目里大部分时间花在业务交互上不要在炫技上浪费太多时间。第四个建议是给地图应用留一个“无网络模式”哪怕只是能看之前缓存的标记点也会让用户在信号不好的野外或地下停车场里对你的工具增加极大的信任感。做一个工具类项目如果只给自己用最难的不是功能而是数据从哪来、怎么长期积累、怎么容错恢复。lingbot-map 这个项目给我的最大收获不是代码量或者技术难度而是把“收藏”这个动作从随手一按变成了真正可持续维护的习惯。如果你也经常收藏地点又找不到不妨照着这个思路做一个属于你自己的版本数据模型和交互逻辑比我这个更完善的空间还很大。