前阵子整理手机里的地图收藏夹，发现一个尴尬的事实：我收藏了两百多个地点，但真正要用的时候一个也想不起来。它们分散在不同地图应用、聊天记录和截图里，分类只有“想去”和“收藏”两种状态，至于“为什么想去”“和谁一起去”“大概预算多少”这些信息，全都丢在记忆深处。于是我用周末时间写了 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 里反着来，先花一晚上设计数据模型，再动界面。这个顺序省了我后面至少两周的返工时间。
一个标记点最终确定的字段如下表：
| 字段 | 类型 | 用途说明 |
|---|---|---|
| id | string | 唯一标识，写死了不可变，用来关联路线和导出数据 |
| name | string | 地点名称，用于列表展示和搜索 |
| latitude / longitude | number | 经纬度，采用 WGS-84 标准，所有图源叠加问题时统一转换 |
| category | string | 分类，如美食、住宿、机位、露营地，用于图表筛选 |
| note | string | 自由文本备注，用来记录“为什么收藏它” |
| tags | string[] | 标签列表，支持一对多描述，如“小众”“夜景”“要预约” |
| photos | string[] | 图片链接数组，只存外链，不存二进制数据 |
| rating | number | 个人评分 0-5，用于后期筛选和排序 |
| visit_status | enum | 想去 / 已去 / 已放弃，方便做行前筛选 |
| create_time | datetime | 创建时间，用于排序和统计 |
这个表用起来之后我才发现，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。对比起来各有利弊。
| 对比维度 | Leaflet | MapLibre 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 这个项目给我的最大收获，不是代码量或者技术难度，而是把“收藏”这个动作从随手一按变成了真正可持续维护的习惯。如果你也经常收藏地点又找不到，不妨照着这个思路做一个属于你自己的版本，数据模型和交互逻辑比我这个更完善的空间还很大。
