lingbot-map 这个项目名第一次出现在我们仓库里时，大家的第一反应都是“这是什么”。项目代号里的人脸是个跟得住的内部玩笑，说是“灵巧机器人”，其实跟机器人没多大关系。它是我们那段时间被地图可视化反复毒打之后沉淀出来的一个模块——负责行政区域边界渲染、点数据聚合、区域联动、下钻交互。没有商业地图组件那么多包袱，也不需要为用不到的能力付费。如果你正在做门店分布、区域统计、网格运营看板这类带地图的大屏或后台系统，一直被现成组件的高亮、联动、大数据量帧率问题卡住，这篇文章就是你想找的那种“拆开看+抄作业”的参考。
1. 从一次业务事故说起：为什么最后自己画地图
1.1 被“现成组件”反复折磨的业务场景
事情的起点其实很朴素。那段时间我们要做一块“全国门店分布与区域销售统计”的看板，要求有三：第一，各省份要能按指标值填充不同深浅的颜色；第二，鼠标悬浮要显示该省份的汇总数据；第三，点击某个省要能下钻到下一级行政区，同时联动旁边的柱状图和明细表。
听起来都是地图组件的基本功能，对不对？但真做起来就发现，通用组件的问题恰恰出在“通用”上。它们的默认交互策略是给自己设计的，不是给你的业务设计的。我要做的是在一堆 API 和回调里反复“硬拗”，把一个通用工具往自己的业务形态里掰。区域高亮样式要改、悬浮提示要自定义、下钻动画要控制、和大数据点位同时渲染时帧率还会掉到没法看。
那段时间有位同事每天的工作就是跟地图组件搏斗。改一个颜色要通过三层配置，调一个联动要写一大堆事件监听，最后还要面对一个几百 KB 的运行时和一堆用不上的内置图层。
1.2 从“灵巧机器人”到 lingbot-map
后来我们做了一个决定，干脆把地图这一块从业务代码里抽出来，做成一个独立模块。命名的时候没有太多仪式感，内部机器人的代号叫“lingbot”，顺手就用了，加个 map 后缀代表地图模块。lingbot-map 就这样进了仓库。
它要解决的问题非常聚焦：
- 渲染省、市、县三级行政区划边界，支持区域填色和描边。
- 渲染海量业务点位，要求不同密度下缩放、拖拽都跟手。
- 区域与点位的点击命中、悬浮高亮、钻取联动。
- 不依赖重量级地图平台，离线可用，便于内网部署。
- 所有交互行为可控，样式完全自定义。
这套定位决定了它的技术选型和实现方式都跟“拿来就用”的通用地图组件不一样。它更像一个针对自身业务深度定制、但又保留通用能力的地图渲染引擎。
2. 数据进得来才画得对：坐标、边界与体积三道关
2.1 坐标系：地图错位几十公里的元凶
地图可视化第一个坑，几乎都出在数据坐标上。我见过不止一个项目，第一版上线后发现点位和行政区边界错了几百米甚至几十公里，第一反应全是“渲染代码写错了”，查了半天才发现是两个数据源的坐标系根本不是一回事。
WGS84 是目前互联网上最常见的地理坐标标准，GPS 原始输出就是它。但很多底图服务为了合规和保密，会对真实坐标做一次非线性偏移，形成一个近似坐标体系，业内习惯统称为“火星坐标”。更细分还有地方坐标、投影坐标等。
lingbot-map 的坐标处理原则只有一条：进入渲染管线之前，所有数据必须统一到一个坐标系。具体做法是：
- 所有外部业务点数据，在入库或导入时统一转换为目标坐标系。
- 行政区边界数据同样做一次坐标统一。
- 项目范围内的投影计算、命中检测、渲染，全部基于统一后的坐标。
- 底图如果要叠加第三方图片或瓦片，单独做一层坐标纠偏适配，不污染核心数据层。
2.2 行政区边界：GeoJSON 从哪来，怎么“瘦身”
行政边界数据最常用的格式是 GeoJSON，一个 FeatureCollection 里装着若干个 Feature，每个 Feature 的 geometry 是 Polygon 或 MultiPolygon，形状由一串经纬度坐标点描述。
拿到原始数据之后的处理流程是固定的：清洗 -> 分级 -> 简化 -> 输出。清洗是去掉一些行政区划调整后遗留的冗余或无效字段。分级是按照国家、省、市、县把数据拆成多个文件，避免一次加载全部层级。简化是最关键的一步，原始数据往往精度极高，全国县界几十 MB 不稀奇，直接扔进浏览器会卡到怀疑人生。
简化算法最常用的是 Douglas-Peucker 折线简化。它的思路很直观：先找到一条折线中离首尾连线最远的点，如果这个距离超过阈值就保留，否则删掉，然后递归处理。阈值越大，保留的点越少，边界越粗糙。全国尺度看，阈值取 0.001 到 0.01 度左右通常能在观感和体积间取得不错平衡。到市级缩放时用低阈值精细边界，到全国缩放时用高阈值粗边界，这就是分级加载的意义。
2.3 数据体积与瓦片化思路
纯数据体积控制在几 MB 以内后，还有个问题是渲染性能。如果每次都把几万个坐标点丢给 canvas 硬画，每帧都在重复计算所有多边形，再好的机器也扛不住。
lingbot-map 的做法是按需加载加瓦片化：把地图切成多个缩放等级，每个等级把可视区域内的数据再切成固定大小的瓦片块，缩放或拖拽时只加载当前视口需要的瓦片。这个思路和地图服务的瓦片机制一样，区别在于我们的瓦片是“业务数据层”而非底图图片。
提示：如果你要处理的不只是行政区边界，还有大量散点，建议把数据同样按网格索引切块。查询“某个范围内有哪些点”时先用网格粗筛，再做精确距离判断，能省掉大量无效循环。
3. 渲染管线拆开看：从投影、画多边形到点击命中
3.1 经纬度到屏幕坐标的投影计算
屏幕是一个二维平面，而地理坐标是经纬度球面数值。把经纬度“拍”到屏幕上，需要一套投影计算。lingbot-map 用的投影方式是简化版的墨卡托投影。
核心公式并不复杂，关键是理解参数：
function project(lon, lat, center, scale) { return { x: (lon - center.lon) * scale, y: (center.lat - lat) * scale // 纬度越大越靠上 }; }center 是当前视角中心，scale 是缩放系数。坐标差值乘以缩放系数，就得到了相对中心的屏幕偏移。这套线性映射对绝大多数国内业务场景够用。如果要做世界地图，则需要更严格的正球墨卡托公式：
function projectMercator(lon, lat, center, scale) { const x = (lon - center.lon) * scale; const y = Math.log(Math.tan(Math.PI / 4 + (lat * Math.PI) / 180 / 2)) * scale; return { x, y }; }投影计算是整个渲染的基础，所有后续绘制、命中检测、瓦片坐标换算都从这里展开。
3.2 Canvas 绘制多边形：填色和描边要注意什么
拿到投影后的坐标点，下一步就是绘制。渲染目标选的是 Canvas 2D，而不是 SVG 或 WebGL，原因是它性能足够、兼容性好、实现复杂度适中。
绘制一个区域的代码大致是这样：
function drawPolygon(ctx, ring, projection) { ctx.beginPath(); ring.forEach((point, index) => { const p = projection(point[0], point[1]); if (index === 0) ctx.moveTo(p.x, p.y); else ctx.lineTo(p.x, p.y); }); ctx.closePath(); ctx.fill(); ctx.stroke(); }但这里有个非常容易翻车的细节：如果直接遍历所有省份，各自填充、各自描边，会发现相邻省份之间会出现一道细缝或白线。原因是不同多边形独立描边时，相邻边界产生抗锯齿叠加，颜色变浅或变深。
解决方法是把“生成路径”和“绘制”分成两个阶段。先用一个 path 把全部多边形合并成一个整体路径，最后统一 fill 和 stroke：
function buildRegionPath(ctx, regions, projection) { ctx.beginPath(); regions.forEach(region => { region.rings.forEach(ring => { ring.forEach((p, i) => { const pos = projection(p[0], p[1]); i === 0 ? ctx.moveTo(pos.x, pos.y) : ctx.lineTo(pos.x, pos.y); }); }); }); }填充颜色时再根据每个区域的数据单独处理——用 clip 限制填充范围，或者按区域分别生成子路径并缓存。
3.3 点击命中检测：射线法的朴素实现
点击一个区域后，怎么知道点的是哪个省？Canvas 本身不提供“点是否在多边形内”的 API，需要自己做命中检测。
我想过把每个区域绘制到离屏 canvas 上再用像素取色来判断命中，但最稳定通用的还是射线法：从点击点发出一条水平射线，统计它穿过多边形边的次数，奇数次在内部，偶数次在外部。
function pointInPolygon(point, ring) { let inside = false; for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) { const xi = ring[i][0], yi = ring[i][1]; const xj = ring[j][0], yj = ring[j][1]; const intersect = ((yi > point.y) !== (yj > point.y)) && (point.x < (xj - xi) * (point.y - yi) / (yj - yi) + xi); if (intersect) inside = !inside; } return inside; }命中检测的性能取决于多边形点数和区域数量。通常的做法是：先根据可视区域做边界盒粗筛，把“明显不可能包含该点”的区域筛掉，再对剩余区域逐一做射线法。一次点击处理的区域数量通常在个位数，性能完全够用。
4. 交互体验的取舍：缩放、下钻与看板联动
4.1 缩放和拖拽：围绕鼠标中心缩放
地图看板和纯静态图表的本质区别在于：用户会缩放、平移、点击、下钻。这些交互如果只靠浏览器默认行为，体验会非常生硬。
缩放最简单高效的方案是围绕鼠标位置缩放。思路是：记录鼠标在屏幕上的位置，换算成当前视角下的经纬度，再缩放，然后把视角中心调整到刚才那个经纬度点仍然停留在鼠标下。这样光标指向哪里，哪里就放大，符合直觉。
function zoomAt(center, offset, scale, nextScale, mouseScreen) { const beforeLat = center.lat - offset.y / scale; const beforeLon = center.lon + offset.x / scale; // 新的中心要根据缩放系数重新计算 const newCenter = { lon: beforeLon - mouseScreen.x / nextScale, lat: beforeLat + mouseScreen.y / nextScale }; return { center: newCenter, scale: nextScale }; }拖拽就更直接了：记录每次 mouse 移动的相对位移，直接修改视角中心的 offset。整个过程不涉及任何 DOM 重排，只改几个变量，然后触发重绘。
4.2 下钻的层级切换策略
从省到市到县，数据量级会指数增长。如果加载全国县级边界，体积和绘制开销都不小。
lingbot-map 的下钻策略是“按需加载、逐级替换”：最开始的视角只有全国省级边界，数据文件只有几百 KB；点击某个省后，局部加载该省的市级边界，并只渲染当前视口范围内的市。到达市级视角后再加载县级边界。这样每一层级的最大数据量都可控。
一个细节是，切换到下级地图时，当前区域的填充状态、联动选中状态要能无缝过渡。做法是把“区域状态”和“区域边界数据”分离存储，区域状态（选中、悬浮、颜色）用 id 管理，不管地图切到哪一级，只要 id 还存在，状态就保留。
4.3 与统计图的联动：事件总线设计
地图不是孤岛，它要和旁边的图表、表格做联动。一个省份被悬浮时，旁边的列表要滚动到对应行；一个区域被点击时，柱状图要重新过滤数据。
联动设计不复杂但容易写出乱麻。最稳妥的是把地图内部事件收敛成几种标准动作，再通过一个事件中心对外广播：
- region:hover：区域 id，悬浮位置
- region:click：区域 id，点击层级
- region:enter / region:leave：视角跨度变化
表格、图表只需要订阅这些事件，不需要感知地图内部绘制细节。反过来，外部组件想改变地图状态，也只通过一个 setState({ selectedId, drillLevel }) 入口进入，不直接碰地图内部变量。这样双向联动的代码都会很干净。
5. 实测中踩过的四个坑：坐标偏移、边界闪缝、大数据卡顿、移动端手势
5.1 坑一：业务数据与行政边界错位
第一版 demo 上线后，内网的测试同事很快就反馈：门店点位明显不在它们应该在的省份里，有的偏移看起来甚至跨了两个地级市。
排查路径是控制变量。先把行政边界单独渲染，看起来是正常的。再把散点单独渲染，也看不出来问题。合到一起就错了。用几个城市坐标做基准点，和边界上的地理标记点一对比，才发现业务数据用的坐标系和边界数据完全不一样。最后在数据导入阶段统一转换，问题一次解决。
提示：在任何地图项目里，坐标系统一一定要在最前面完成。等到数据已经进入业务库再统一，要处理历史数据、增量数据、缓存数据，时间成本至少翻一倍。
5.2 坑二：全国点数据一次渲染白屏
有段时间我们接了一批全国范围的设备点位，十几万个点一次性丢到渲染层。初次进入页面时浏览器直接白屏好几秒，之后每次拖拽都像幻灯片。
本质原因是把不该在初始化时做的事全做了一遍：把所有点一次性投影计算、全部 startPath、全部绘制到主 canvas。
优化很快就有方向：
- 打开页面只渲染当前视口内和视口边缘预载区域内的点。
- 超过一屏的点，绘制前先按屏幕坐标做空间网格分级，远距离的层级只画“代表点”。
- 点绘制改为“离屏 canvas 合层”，先把静态底图和一些不变图层绘制到离屏 canvas 上，拖拽缩放时直接贴图，只有点位状态变化时才重绘动态层。
改完以后白屏时间降到了几百毫秒，拖拽总算回到正常帧率。
5.3 坑三：相邻区域之间的缝隙和重叠
行政区边界来自不同的数据源，相邻区域之间理论上应该完全贴合，但实际数据会有零点几像素到几像素的误差。你直接一个区域一个区域地 fill 和 stroke，屏幕上就会出现明显的白色缝隙或暗色重影，强迫症视角根本没法看。
这里有个经验值：对于 canvas 渲染，stroke 线的宽度建议是 1.5 到 2 像素。太细会被抗锯齿吃掉，太粗又会盖住填色过多区域。同时把描边绘制放到底层，先描边再填色，利用填色去压住相邻区域之间那条缝。
更彻底的办法是让同一层级的区域边界共用同一条边，只维护一张无向邻接表。渲染时每个多边形只画自己独有的外部边，公共边只画一次。这样可以彻底消除缝隙，但对数据处理的要求高很多，一般项目优先考虑描边 + 填色的技巧方案就够了。
5.4 坑四：移动端双指缩放不生效
大屏项目做多了，移动端适配就差一口气。我们的第一版交互只做了鼠标 wheel 和 drag，手机上双指缩放完全没反应。
移动端的核心事件是 touch 事件，需要自己维护一个活动触点列表。双指缩放的计算逻辑是：
function calcPinchScale(touches) { const distance = Math.hypot( touches[1].clientX - touches[0].clientX, touches[1].clientY - touches[0].clientY ); return distance; }以两点距离的比值作为缩放比例，配合触点中心点作为缩放中心，就能实现和桌面端一致的“围绕中心缩放”手感。
注意：移动端页面最好禁掉默认的 touchmove 和长按选中行为，否则画布会跟着页面滚动或弹出系统菜单。通过 CSS touch-action: none 可以避免大部分问题。
6. 性能优化实测：从白屏卡顿到保持 60 帧
6.1 离屏 Canvas：把静态内容画一次
地图渲染性能最立竿见影的优化，就是离屏 Canvas。把不变的内容（行政区边界、底色、网格线）先画到另一个不可见的 canvas 上，主 canvas 每次重绘时直接把这张图 drawImage 上去，再画动态内容。拖拽缩放时，只需要对离屏 canvas 做一次变换绘制，而省去了重新计算几千个点、重建路径的大量开销。
function renderFrame() { ctx.clearRect(0, 0, width, height); ctx.setTransform(scale, 0, 0, scale, offset.x, offset.y); ctx.drawImage(offscreenCanvas, 0, 0); drawPoints(); }这个简单的结构省掉了每次重绘时全部区域路径的计算，实际效果非常明显。
6.2 局部重绘：能改多少就改多少
最初我们的实现是任何一个小区域变色，就整个 canvas 重绘一遍，全国几百个区域全走一遍射线命中和路径计算。后来改成“脏矩形”思路：记录需要更新的区域列表，重绘时先用 clip 限定重绘范围，只重画受影响区域。
对应的区域填色变化、点位高亮、tooltip 移动，都属于高频小范围更新，全部走局部重绘。全图级别的重绘只留给地图拖拽、缩放和层级切换。
6.3 图层分级与数据抽稀：只画人眼看得见的精度
地图是典型的多分辨率场景。全国缩放下，县级边界绝大多数时候都小于像素大小，没必要全部绘制。lingbot-map 的做法是按当前缩放级别选择数据精度等级：
- 全国视野：仅省级边界，市级点位做网格聚合，一个网格里只保留一个代表点。
- 省级视野：市级边界 + 县级边界按需，散点按网格粗过滤。
- 市级及以下视野：完整县级边界，散点全部展示，但大量距离接近的点做像素级合并。
散点像素级合并是另一个性价比极高的优化。将屏幕坐标按整数取整后放入 hash 表，同一像素格内只画一个点或画一个带数量的圆。对于几十万点的场景，这一步能把绘制点数直接压到几千以内。
6.4 极致调优后的实测效果
这套优化落实后，我们用一份包含全国省级边界、300 多个市级边界和 15 万个业务点的数据集做了实测。优化前：
- 初始加载白屏约 5-8 秒。
- 拖拽缩放帧率不稳定，明显掉帧。
- 内存占用峰值偏高。
优化后：
- 初始加载约 1-2 秒完成首帧。
- 拖拽缩放稳定在 50-60 帧。
- 点击命中、悬浮高亮响应延迟在 16ms 以内。
对大多数业务场景来说，这个表现已经非常够用了。如果再继续往更极致的方向优化，可以引入 WebGL 做并行计算和批量绘制，但那是数据量达到百万级以上时才需要考虑的范畴。
回过头看，lingbot-map 能沉淀下来的核心经验并不是某一处奇技淫巧，而是一个清晰的思维框架：先统一坐标，再控制数据量，然后把渲染过程拆成静态层和动态层，最后通过合理的交互事件设计，把地图真正融进整个业务系统里。如果你也要做一个类似的东西，希望这些踩坑记录能帮你少走几趟弯路。
