1. lingbot-map 到底解决了什么问题

lingbot-map 是我在做一个小型室内巡检机器人时顺手沉淀出来的地图模块。名字本身很直白：lingbot 是当时那个机器人项目的代号，map 就是它身上那块地图能力。整个项目做下来，它变成了一套轻量、可私有化部署、以瓦片缓存为核心的离线地图服务，适合嵌入式设备、室内机器人、园区安防这类“不想把地图数据交给别人，又不想被商业地图 SDK 绑定”的场景。

先说清楚它解决了什么。我当时的机器人需要在楼栋里按计划巡检，后台要能看到机器人实时位置、历史轨迹，还要能定位附近的 POI。直接接商业地图 SDK 当然省事，但问题不少：室内没有可用的公共底图，定制楼层边界、设备点位、区域热区都要额外收费；设备处在内网环境，外部地图服务一断就白屏；而且拿第三方地图底图存自己设备上，许可和合规上很容易踩坑。所以我的结论很明确：地图能力必须自己做，而且必须离线、必须够轻。

这个项目适合谁参考？两类人。一类是正在搞机器人、无人机、巡检设备、IoT 网关的开发者，手头需要一个不依赖公网的地图底座；另一类是做城市级或者园区级可视化大屏的人，想自己控制底图和图层样式，不想被厂商方案锁死。如果你只是想快速出一张“世界地图”给别人看，那 lingbot-map 不是最优解，直接用成熟的地图 SDK 更合适。但如果你要的是“我能完全控制地图数据、瓦片格式、渲染逻辑、离线存储”，那这套东西的价值就出来了。

2. 整体架构与核心设计

2.1 模块划分

lingbot-map 并不是一个很大的框架，它拆完之后核心模块就四个：

• tile-service：静态瓦片服务，负责把瓦片从本地存储里读出来返回给客户端。
• tile-builder：离线瓦片生成工具，把 GeoJSON 格式的地图数据渲染成 PNG 瓦片，写入 SQLite。
• map-renderer：前端极简渲染层，用 Canvas 把瓦片拼接成地图，并且支持在上面画轨迹、点位、热区。
• poi-store：离线 POI 和检索服务，用 SQLite 自带的全文索引做关键词搜索。

这个模块划分是我改了三版之后才定下来的。第一版用了一个已有的地图渲染库，确实功能多，但引入体积太大，而且库升级时接口经常变。第二版我把渲染逻辑写进了机器人主进程，结果主进程一忙地图就卡。后来才想明白，地图这种功能应该保持“服务化”而不是“函数化”，独立成模块之后，不管机器人端、Web 端、还是大屏端，都通过同一个 HTTP 接口拿瓦片，数据源统一，调用端反而更简单。

2.2 瓦片金字塔与 LOD

地图瓦片的核心概念是“金字塔结构”。如果把整个世界地图看成一层层切片，那么第 0 级是一张 256×256 的图，把全世界塞进去；第 1 级横向和纵向各切一刀，变成 4 张 256×256 的瓦片；第 2 级再切，变成 16 张。每增大一级 zoom，瓦片数量变成原来的 4 倍，但每一张仍然保持 256×256。

这就是 LOD，Level of Detail，层级细节。低 zoom 看整体，高 zoom 看细节。对机器人巡检这种场景来说，我们只需要局部区域的 15 到 19 级，所以生成的瓦片数量是可控的。一个园区大概几百米到几公里的范围，20 多级才几百上千张瓦片，存储量非常小，整个 SQLite 库可以控制在几十 MB 以内。

你可能会问：直接把一张大地图切给客户端不就行了？我的经验是不行。一个 20 级的大 PNG 可能有几十 MB，客户端一次加载要好几秒，拖动地图要反复重绘，内存压力也很大。瓦片方案像自助餐厅的“小碟分装”，每碟只装眼前那几口，边缘设备才能吃得动。

2.3 为什么选“瓦片 + 本地缓存”而不是现成地图

刚开始有同事建议直接引地图 SDK，说配置一下就能用。我把需求拉出来逐条对了一下，发现真正需要的不是“整个世界的地图”，而是“我们这一栋楼和周边区域的地图”。在这个前提下，现成地图服务会有三方面问题：

第一，离线问题。机器人在楼里跑，楼宇内网络覆盖率并不能保证。一旦请求失败，商业地图 SDK 经常显示空白的灰色底图，后台的大屏直接变成故障现场。自己做瓦片服务之后，数据放在本地 SQLite 里，就算局域网所有服务器都挂了，只要设备本地有缓存库，地图照样能画出来。

第二，数据控制权。巡检点位、危险区域、门禁位置这些都算业务敏感数据，不应该在别人的地图服务上标点。自己存瓦片和 POI，数据流程完全掌握在手里，导出备份、迁移、删除都非常干净。

第三，定制成本。商业地图底图的室内图层往往不够准确，高亮区域、动态区域、自定义颜色都有限制。自己渲染的话，想要什么样式就画什么样式：消防通道标红、巡检路线标蓝、温控区域图上色，全都是自己写的逻辑。

基于这三点，我最后确定的技术路线是：本地 GeoJSON 作为数据源，脚本渲染成 PNG 瓦片，SQLite 作为瓦片和 POI 的存储，HTTP 接口对外提供瓦片和检索能力。整个链路所有东西都在自己的代码和本地存储里，没有一家第三方厂商介入。

3. 核心实现拆解：从坐标到瓦片

3.1 经纬度到瓦片坐标的计算

做地图服务，第一个硬骨头就是坐标换算。这里我用的是 Web 墨卡托投影体系，也就是互联网地图常用的那套世界观。经纬度本身是球面坐标，瓦片是平面坐标，中间必须经过投影转换。

核心是一组公式。给定一个经纬度和 zoom 层级，可以算出它落在哪一张瓦片上。我直接给出我代码里在用的实现，前端和后端统一用这一套，避免两边计算结果不一致：

function lonToTileX(lon, zoom) { return Math.floor(((lon + 180) / 360) * Math.pow(2, zoom)); } function latToTileY(lat, zoom) { const limit = 85.0511287798066; if (lat > limit) lat = limit; if (lat < -limit) lat = -limit; const latRad = (lat * Math.PI) / 180; const n = Math.pow(2, zoom); const y = (1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2 * n; return Math.floor(y); } function tileToLon(tx, zoom) { return (tx / Math.pow(2, zoom)) * 360 - 180; } function tileToLat(ty, zoom) { const n = Math.PI - 2 * Math.PI * ty / Math.pow(2, zoom); return (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n))); }

可能有细心的朋友注意到 lat 方向我做了 85.05 的 clamp。这是墨卡托投影本身的特性，纬度到 90 度时，tan 函数会趋向无穷大，公式直接算崩，所以地图行业普遍把最大纬度限制在这个值附近。

这个公式我建议不要自己凭感觉写。我第一次实现时以为就是简单的线性缩放，把 90 纬度直接套进去，结果生成出来的瓦片在高纬度区域完全变形成一条直线，排障排了半天。最后对照标准公式重写才恢复正常。坐标换算这种基础函数，能用标准实现就别自己发明。

3.2 瓦片服务端的存储与查询

瓦片生成出来之后，需要一个地方存放。我用的是 SQLite，按 (z, x, y) 三个字段作为主键，数据直接以 BLOB 形式存 PNG 二进制。表结构不复杂：

CREATE TABLE tiles ( z INTEGER NOT NULL, x INTEGER NOT NULL, y INTEGER NOT NULL, data BLOB NOT NULL, PRIMARY KEY (z, x, y) );

为什么用 SQLite 而不是直接放文件目录？起初我也试过文件夹方式，zz/xx/yy.png 这种结构，看起来直观，但问题是文件数量一多，文件系统遍历开销就上来了，而且热更新、备份、传输都不如一个单文件库省事。SQLite 一个文件就能装下全部瓦片，设备之间拷贝、增量同步、加索引都非常简单。

HTTP 服务端也很薄，一个路由就够。下面是一段最简实现：

const http = require('http'); const db = require('./db'); // 封装好的 SQLite 访问层 const server = http.createServer((req, res) => { const match = req.url.match(/^\/tiles\/(\d+)\/(\d+)\/(\d+)\.png$/); if (!match) { res.writeHead(404); res.end('Not Found'); return; } const z = Number(match[1]); const x = Number(match[2]); const y = Number(match[3]); const tile = db.getTile(z, x, y); if (!tile) { res.writeHead(404); res.end('Tile Not Found'); return; } res.writeHead(200, { 'Content-Type': 'image/png', 'Cache-Control': 'public, max-age=86400' }); res.end(tile.data); }); server.listen(8080);

这段代码看着简单，但里面有几个细节我会提一下。第一，Cache-Control 必须设置。虽然服务在局域网内，但重复请求瓦片会白白占带宽，加了缓存之后，同一个客户端短时间内不会重复请求同一张瓦片。第二，404 不能省。有些前端会自动请求范围之外的瓦片，如果不返回 404 而返回 200 加空白图，会导致前端认为数据存在，白屏问题排查会非常困难。第三，我在路由匹配里直接限定数字，避免字符串拼接出 x/y/z 的问题，这是我早期踩过的一个安全边界。

3.3 前端最小渲染示例

有了瓦片服务之后，前端的渲染逻辑其实是最简单的部分。我用的主力方案是 Canvas，不引入大型地图框架。核心思路是：确定当前视野中心对应的瓦片编号，然后算出屏幕范围内所有瓦片的位置，逐个画到 Canvas 上。

下面这个函数可以解决“给定中心和 zoom，渲染周围一圈瓦片”的需求：

function drawMap(ctx, centerLon, centerLat, zoom) { const cx = lonToTileX(centerLon, zoom); const cy = latToTileY(centerLat, zoom); const range = Math.ceil(ctx.canvas.width / 256 / 2) + 1; for (let dx = -range; dx <= range; dx++) { for (let dy = -range; dy <= range; dy++) { const tx = cx + dx; const ty = cy + dy; const img = new Image(); img.onload = () => { ctx.drawImage( img, (tx - cx) * 256 + ctx.canvas.width / 2 - 128, (ty - cy) * 256 + ctx.canvas.height / 2 - 128 ); }; img.src = `/tiles/${zoom}/${tx}/${ty}.png`; } } }

这里有一个很不显眼但很重要的点：图片是异步加载的。如果直接用同步 onload 全部开始加载，瓦片回来顺序是乱的，会出现地图碎片先闪一下再拼完整。我后来加了一个简单的“瓦片加载完成计数”，等首屏瓦片全部到位后再一次性呈现，体验会稳很多。另外不要忘记清空画布：

ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);

不 clean 的话，上一帧残留边缘会越叠越多，看起来像残影，这不是渲染库的 bug，是 canvas 合成原理本身如此。

4. 离线 POI 与检索

4.1 数据结构与索引

地图光有底图还不够，还得有“地点”。巡检机器人要找充电桩、找门禁、找消防设备，靠人工在界面上看太累，我加了一个轻量的离线 POI 检索模块。数据表设计如下：

CREATE TABLE pois ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, lat REAL NOT NULL, lon REAL NOT NULL, category TEXT, floor INTEGER DEFAULT 0 ); CREATE VIRTUAL TABLE pois_fts USING fts5(name, category);

POI 数据录入很简单，从 Excel 或者 JSON 导入都行，但全文索引需要触发器和主表同步。我用 SQLite FTS5 的时候，第一次忘了加触发器，导致搜索出来全是旧数据，看起来很诡异。所以正确的做法是让主表和 FTS 索引同步更新：

CREATE TRIGGER poi_ai AFTER INSERT ON pois BEGIN INSERT INTO pois_fts(rowid, name, category) VALUES (new.id, new.name, new.category); END; CREATE TRIGGER poi_ad AFTER DELETE ON pois BEGIN INSERT INTO pois_fts(pois_fts, rowid, name, category) VALUES ('delete', old.id, old.name, old.category); END; CREATE TRIGGER poi_au AFTER UPDATE ON pois BEGIN INSERT INTO pois_fts(pois_fts, rowid, name, category) VALUES ('delete', old.id, old.name, old.category); INSERT INTO pois_fts(rowid, name, category) VALUES (new.id, new.name, new.category); END;

FTS5 的 update 和 delete 是通过特殊语法实现的，这个和普通业务表不一致，很容易被忽略。我整理文档时会额外标红这一块：如果你看到 FTS 表数据明明很少，但搜索量很大，先检查删除/更新触发器是不是只插不删，索引很可能会“幽灵数据”残留。

4.2 检索接口

检索逻辑相对直接，用 FTS5 的 MATCH 语法做排名搜索：

SELECT p.id, p.name, p.lat, p.lon, p.category, p.floor, f.rank FROM pois_fts f JOIN pois p ON p.id = f.rowid WHERE pois_fts MATCH ? ORDER BY f.rank LIMIT 20;

接口设计为 GET 请求，参数是 q，比如 /poi?q=充电桩。由于目标是离线环境，不需要做分布式搜索，SQLite 一个查询十几毫秒就能返回，完全够用。

检索的边界条件我也踩过一个坑：搜索“A”和搜索“A ”中间带不带空格，匹配结果不一样，特别是中文输入时用户经常带全角空格。我在服务端做了 trim 和空格规范，再把关键词丢进去，用户体验好很多。另外建议接口层做“拼音搜索”或者“前缀补全”，因为离线设备没有云服务帮忙纠错，这个方案可以显著提升可用性。

5. 实操过程记录与常见坑

5.1 实测过程中遇到的情况

我拿 lingbot-map 在实际园区环境里跑过三轮，第一轮最典型的问题是“地图偶尔白屏”。排查下来，不是服务端瓦片缺失，而是前端计算 visible range 的时候把边界算小了，屏幕边缘的瓦片请求没发出，于是滚动到边缘时就缺一块。这个修复很简单：range 加 1，多预取一圈瓦片即可。

第二轮遇到的是坐标偏移。因为我把经纬度直接近似成了瓦片像素坐标，忽略了 Web 墨卡托在 Y 方向上的非线性变形，导致轨迹点和底图位置偏了几十米，这在园区里已经非常严重了。修复办法就是上文提到的统一用标准的 lonToTileY 函数，并且让前端和后端使用同一份坐标转换代码，避免两套逻辑。

第三轮是性能问题。当加载了 200 多张瓦片之后，Canvas 每帧重新绘制整张图，机器人控制端帧率掉到十几帧。后来我把“地图渲染”和“轨迹叠加”分成两个 Canvas 层，底图层只画一次，轨迹层单独刷新，性能一下就上来了。

5.2 常见问题速查表

5.3 避坑经验

我特别想强调一个点：瓦片服务的定位语义和普通接口不一样。普通接口请求体里面是业务参数，而瓦片请求 /tiles/15/12345/6789.png 一旦写错，往往不是 404，而是“别人冒用你的地址”或者“前端反复请求同一张错误瓦片”。所以一定要在路由层面做严格的整数限制，不能直接用正则的 . 匹配到底。另外，如果瓦片要对外提供，别把 SQLite 文件路径直接暴露在 URL 里，老老实实走一层服务端翻译。

还有个小技巧，生成瓦片时可以同时生成一个 manifest 文件，记录生成的 zoom 范围、边界经纬度、版本号。前端加载前先读取 manifest，就知道当前区域支持哪些层级，不支持的层级直接降级到父级瓦片，而不是显示空白。这个设计在低端设备上特别管用，因为边缘设备的内存和网络带宽都很紧张。

6. 扩展场景与影响范围

lingbot-map 这套东西做完之后，能发挥作用的场景远不止一台巡检机器人。我后来陆续看到它可以套用到这些地方：

• 楼宇可视化大屏：把楼层平面图、设备位置、告警点位全部做成 GeoJSON，不用依赖外部底图。
• 园区安防系统：摄像头、门禁、巡逻路线这类数据天然适合离线瓦片存储，查询速度比传统地图引擎快很多。
• 车机或者工业平板：在信号弱的仓库、矿场、地下车库等场景，设备需要一个永远在线的地图底座。
• 多机器人协同：每台设备都带一份瓦片库，不会因为中心节点挂了就失去导航能力。

如果继续往下扩展，我认为 lingbot-map 可以做的事情还有不少。比如加一个“动态图层”功能，让后台通过 WebSocket 推送实时轨迹和告警区域给前端，这个做完之后，地图就不只是“一张静态底图”了，它会变成一个实时可视化中心。再比如把瓦片生成脚本做成热更新任务，当 GeoJSON 数据变化时自动重新渲染相关瓦片，不用人工跑批，这就是一个挺完整的“地图数据闭环”。

我个人在实际操作中最深的体会是：地图项目看起来门槛高，但真正难的不是渲染，不是瓦片格式，而是“数据从哪来、坐标怎么统一、更新流程怎么设计”这三件事。lingbot-map 把这几件事压到最小闭环里——一个 GeoJSON 文件进去，一串 PNG 瓦片出来，挂在本地端口就能被任何客户端消费。这种“越简单越可靠”的思路，反而让它在实际项目里比那些大而全的地图框架更耐折腾。如果你手头也遇到类似的内网地图需求，建议先别急着接大 SDK，把一个最小瓦片闭环跑通，再想着加花活。