一套 three.js 地图引擎从瓦片请求、图层渲染到相机交互做完后我遇到的最大困扰不是“功能没实现”而是“出了 bug 我看不见”。前 8 篇我把视野裁剪、LOD 切换、缓存淘汰都跑通了可一旦画面上一块瓦片莫名其妙消失或错位我根本不知道是请求层的问题还是几何层的问题还是瓦片索引算错了。这个系列的第九篇我决定把调试能力当成引擎的一部分来补一个是 TileKey 线框把瓦片编号对应的实际边界直接画在三维场景里让抽象的“z/x/y”变成肉眼可见的格子另一个是 cursor 坐标探针鼠标随便停在一个位置立刻回传当前光标命中的世界坐标、经纬度、所在 TileKey 和瓦片内相对偏移省得每次怀疑算法时还要人工算一遍。先说明白一点标题里的 cursor 指的就是鼠标光标不是网上那个 AI 编辑器。这里的探针是纯粹的地图调试辅助工具解决的是三维场景里“点到哪里、对应哪个瓦片”的定位问题。如果你正在做自研的 WebGIS 运行时、轻量级三维地图加载器或者只是用 three.js 组织大量瓦片数据这篇的操作应该能直接帮你节省一整天排查时间。1. 弄懂定位为什么瓦片引擎要专门做一套 Debug 图层1.1 瓦片渲染闭环里最容易被忽略的一环很多 three.js 地图项目做到“能显示瓦片”就停了主要精力放在请求队列、纹理上传、LOD 切换这些主线功能上。但到了第 9 篇这个阶段运行时的复杂度已经超出“能不能显示”的范围了。你需要频繁回答这些问题当前视口内到底需要哪些 TileKey实际加载了哪些 TileKey屏幕上这块多边形边界对应的世界坐标是否准确我在鼠标当前位置看到的风景处于哪一个层级、哪一个瓦片的哪一块当 LOD 从第 10 级切到第 11 级时父瓦片和子瓦片的边界是否是同一个面这些问题在系统正常时毫无存在感一旦出问题你要在几万个坐标计算里找一根针。我最初的做法是打 console.log把每次瓦片请求和 key 变化打印出来再手动比对屏幕画面效率极低而且打印过多反而拖慢帧率。TileKey 线框和 cursor 坐标探针出现就是为了把这些原本要靠推理和猜的问题变成直接可见、可直接查询的状态。1.2 线框与探针的分工逻辑两个工具面向上却是同一个目标把瓦片数据结构和三维画面建立一条可视化“对应链”。TileKey 线框承担的是“空间结构可视化”。它会把你运行时里活跃瓦片的边界画在当前场景中相当于把这些 key 对应的 Tile 范围从数据抽象变成几何实体。线框的好处是你可以在一帧画面里同时看到几十上百个瓦片边界立刻判断瓦片拼接缝隙、重叠、错位、缺块等问题。cursor 坐标探针承担的是“单点坐标反查”。当线框告诉你整体结构有问题时探针可以精确锁定鼠标点的坐标归属并给出当前点所在具体是哪个 TileKey两者的边界刚好卡在哪。这种“整体可视化 单点探针”的组合覆盖了瓦片调试中最常见的大部分问题。我建议每个做瓦片地图引擎的人都遵循这个原则先做调试层再做业务层先让 TileKey 可见可查再让瓦片渲染只依赖数据逻辑。否则后续的加载策略优化、裁剪优化全都像在盲改。2. TileKey 的数据底盘把 z/x/y 翻译成三维世界坐标2.1 TileKey 到底是什么TileKey 本身不复杂就是一组金字塔剖分坐标一般写作{z, x, y}。z 代表缩放级别x 和 y 分别代表该级别下瓦片在横向和纵向的编号。整个地球平面被均匀切成了 2^z 列和 2^z 行所以编号范围是 0 ~ 2^z - 1。如果你走 Web Mercator 那一套每个 TileKey 都有一个明确的空间范围。这个范围在数学上也可以反过来写成经纬度范围。比如 z 级下 x 号瓦片的横向占比是(x / 2^z, (x 1) / 2^z)纵向同理。用这个比例乘以地图平面再换算成 world XZ 坐标就是线框的顶点位置。我在这套最小运行时里用的比较简单地图平面直接放在场景的 XZ 坐标上横向是 X纵向是 Z。为了让你读起来顺一点下面的推导全部以“归一化地图坐标”为准也就是把整个世界平面映射到 0~1 的矩形里再乘上你设定好的 worldSize 就能放到场景中。interface TileKey { z: number; x: number; y: number; } // 返回 [minX, minY, maxX, maxY]范围在 0~1 之间的归一化瓦片范围 function tileKeyToUnitRect(key: TileKey): [number, number, number, number] { const size 1 / Math.pow(2, key.z); const minX key.x * size; const minY key.y * size; const maxX (key.x 1) * size; const maxY (key.y 1) * size; return [minX, minY, maxX, maxY]; }如果你还没有 0~1 的地图投影概念可以把它理解成 CSS 里百分比定位一张世界地图缩放到一张正方形图片里每个瓦片就是一个绝对定位的区块百分比是瓦片尺寸相对于世界的比例。TileKey 线框要做的只是把这些百分比区块的边框画出来。2.2 从 TileKey 到场景坐标唯一要小心的符号问题如果你的地图引擎走的是经纬度 墨卡托投影那么最终落地到 scene 坐标时Y 轴方向尤其容易错。three.js 里地面通常放在 XZ 平面也就是横向 X、纵深 Z向上是 Y而 Web Mercator 投影参数里纬度越大越靠上放到场景里就成了 Z 值越小或越大取决于你初始化时怎么定义坐标轴。我这里的约定是地图铺在 XZ 平面上归一化的 y南纬方向投影值对应场景里的 -Z保证北半球的瓦片在纵深负数方向。这个选择不是必须的但一旦定了就要全项目统一。我就是因为这里没有统一导致第一次画 TileKey 线框时线框整体绕 Y 轴镜像翻转视觉上看起来瓦片编号对不上排查了半小时发现是坐标符号反了。所以在接 lineSegments 之前你需要把“地图投影坐标”和“three.js 场景坐标”的转换函数固定成纯函数function unitToScene(u: number, v: number, worldSize: number): THREE.Vector3 { // v 来自归一化 y向上为正这里把 y 反向映射到 Z 轴 return new THREE.Vector3( (u - 0.5) * worldSize, 0, -(v - 0.5) * worldSize ); }这段转换看起来平凡但它决定了线框、瓦片 Mesh、射线命中的坐标是否一致。项目越往后坐标换算出问题的排查成本越高所以我建议把这类函数放在独立的coordinate.ts文件里并写单元测试而不是散落在各模块中手写。2.3 为什么线框不要每次重新构建整个网格瓦片是动态加载、动态卸载的如果每次瓦片集合发生变化都把整个线框几何 rebuild 一遍刷帧速度会很难看。更合理的姿势是把线框当成“瓦片集合的调试投影”通过增量的方式维护。你需要维护从 TileKey 到 segment 索引的映射关系例如使用 Map 来记录某个 key 对应了哪几条线段。当瓦片加载完成、进入活跃状态就添加对应线段当瓦片被淘汰、不再属于活跃集合就删除对应线段。先别急着优化顶点复用先把映射关系和数据流程做对后面性能不够再考虑合并批次。3. 干法选型TileKey 线框用哪种方案画才靠谱3.1 三种施工方案对比我在实现时其实试过三种方案每个瓦片单独用EdgesGeometry生成一个线框 Mesh把每个瓦片的四条边作为独立线段一次次加进 scene以及把多个瓦片的边合并到同一个大LineSegments里。实际体验差异很大这里直接给结论。方案实现复杂度性能动态更新便利性适用场景每个瓦片独立 Mesh低最差高每个对象好控制同时活跃瓦片少于 50 时临时调试每瓦片 LineSegments 一次性加进 scene低较差高不推荐draw call 容易爆炸全局 LineSegments 统一管理中最好中需维护映射活跃瓦片几百上千时推荐最终我选了全局 LineSegments 方案。它的核心思想是不给每个瓦片建对象而是把所有活跃瓦片的边界顶点写进一个 BufferGeometry用一个材质渲染。好处是 draw call 少性能稳定坏处是增删某条边时需要更新对应的 attribute range或者直接全量重建顶点数组。由于瓦片加载本身不是每帧高频发生全量重建顶点数组其实也能接受。除非你的瓦片数量几千个且实时切换非常频繁否则不用一上来就做 range update先把代码写简单实测卡了再优化。全局重建时间在 1000 个瓦片时大概就是几毫秒远低于我的心理预期。3.2 用 LineSegments 生成网格线的核心代码下面是我最终落地的大致代码结构。这里省略了投影细节直接以单位矩形换算成 scene 坐标// TileGridDebugLayer.ts class TileGridDebugLayer { private geometry new THREE.BufferGeometry(); private material new THREE.LineBasicMaterial({ color: 0x35c9ff }); private lineSegments new THREE.LineSegments(this.geometry, this.material); private keyToIndex new Mapstring, number(); // keys: 当前活跃的瓦片 key 列表 updateGrid(keys: TileKey[], worldSize: number) { const positions: number[] []; // 先清空映射后面线框数量少时直接重建量大了再优化增量 this.keyToIndex.clear(); for (const key of keys) { const [u0, v0, u1, v1] tileKeyToUnitRect(key); const p00 unitToScene(u0, v0, worldSize); const p10 unitToScene(u1, v0, worldSize); const p11 unitToScene(u1, v1, worldSize); const p01 unitToScene(u0, v1, worldSize); // 记录这个 key 对应的第一根线在 positions 里的起点下标 const index positions.length / 3; this.keyToIndex.set(${key.z}/${key.x}/${key.y}, index); // 四条边每条边两个顶点 positions.push( p00.x, p00.y, p00.z, p10.x, p10.y, p10.z, p10.x, p10.y, p10.z, p11.x, p11.y, p11.z, p11.x, p11.y, p11.z, p01.x, p01.y, p01.z, p01.x, p01.y, p01.z, p00.x, p00.y, p00.z ); } this.geometry.setAttribute( position, new THREE.Float32BufferAttribute(positions, 3) ); } }这段代码有两点值得注意。第一Y 坐标全部是 0线框就会紧贴地面很容易和瓦片纹理交叉闪烁。我实际使用时会加一个微小的抬升值比如0.02但这个值最好能跟随相机高度动态调整否则拉远视角后线框会陷入地面。第二keyToIndex 记录的是每个瓦片第一条边的起始顶点序号后续要做鼠标悬停高亮时能快速定位到这个瓦片对应的四根线。3.3 动态加载下的更新时机TileKey 线框应该跟随“当前活跃瓦片集合”变化而不是跟随请求响应一次就不管了。我把它接在瓦片缓存管理器的订阅事件里每次瓦片进入 loading、loaded、unloaded 状态时都会触发 DebugLayer.updateGrid。默认情况下这个更新对整个 Grid 全量重建实测瓦片数量不超过 2000 时帧率不会掉。但有一点要克制不能让瓦片请求的每个 Promise resolve 都立刻触发全量重建。我的做法是把更新标记成一个脏标记在下一次 requestAnimationFrame 里统一执行。减少更新次数比减少每次更新的耗时更有效这就是 raster 和 vector 数据调优都遵循的道理。4. cursor 坐标探针鼠标一停立刻回传坐标信息4.1 从屏幕坐标到三维世界的落点cursor 坐标探针的第一步是把鼠标的浏览器坐标转换成 three.js 相机空间下的射线这一步所有 three.js 开发者都写过但地图项目里容易踩到 canvas 不是全屏撑满的坑。你不应该直接用event.clientX / window.innerWidth来算 NDC而应该先拿 canvas 的getBoundingClientRect()把鼠标位置减去 canvas 左上角再除以 canvas 实际宽度高度。const rect canvas.getBoundingClientRect(); const ndcX ((event.clientX - rect.left) / rect.width) * 2 - 1; const ndcY -((event.clientY - rect.top) / rect.height) * 2 1;拿到 NDC 坐标后再设置 raycaster 或直接做射线平面相交raycaster.setFromCamera(new THREE.Vector2(ndcX, ndcY), camera); // 也可以直接用数学方法跟地面平面求交 const plane new THREE.Plane(new THREE.Vector3(0, 1, 0), 0); const target new THREE.Vector3(); raycaster.ray.intersectPlane(plane, target);这里我建议对地面平面优先用数学求交而不是靠射线拾取一个 Ground 网格对象。因为如果你的瓦片 Mesh 是分散的或者带 LOD 切换导致某个位置当前没有 Mesh射线拾取可能落空但数学求交永远不会因瓦片缺失而失效。探针工具最好的状态是“永远有返回值”这样你才能拿结果去判断瓦片状态。如果把探针绑在某个已有的 Mesh 上一旦 Mesh 本身有问题探针也跟着瞎调试价值就废了。4.2 把三维坐标回溯为经纬度、TileKey 和瓦片内偏移拿到 target 后接下来的关键是把它重新投影回地图坐标并换算成当前镜头层级下的 TileKey。实际代码里需要先把场景坐标转回归一化 u、v然后按 zoom 求 TileKeyfunction worldToUnit(p: THREE.Vector3, worldSize: number): [number, number] { const u p.x / worldSize 0.5; const v -p.z / worldSize 0.5; return [u, v]; } function unitToTileKey(u: number, v: number, z: number): TileKey { const n Math.pow(2, z); const x Math.min(Math.max(Math.floor(u * n), 0), n - 1); const y Math.min(Math.max(Math.floor(v * n), 0), n - 1); return { z, x, y }; }你可能会想在探针信息里显示“当前鼠标处于的瓦片”但同时也要显示一个更低层级如 z-1 的瓦片编号这对排查 LOD 切换问题特别有用。我实现的探针面板会同时显示当前缩放层级下的 TileKey、父级 TileKey以及该点距离瓦片四边界的归一化偏移量。显示偏移量有什么好处它让你能立刻看出鼠标是不是正好落在瓦片交界线上。TileKey 里用到的Math.min/Math.max不是多余而是为了防止鼠标在世界边缘外移动时算出负数或越界编号。极端情况下相机允许超出地图边缘负数 TileKey 不是有效 key加个 clamp 才能保证后续用 key 去查缓存不会报错。4.3 探针面板与悬停瓦片高亮的联动探针要真正好用不能只靠文字数字。我的运行时里把探针和线框打通了鼠标移动时计算出当前命中的 TileKey如果这个 key 和上一帧不同就把上一帧悬停瓦片线段的颜色恢复把当前帧悬停瓦片的四条边颜色改成高亮色。线框整体本来是淡蓝色悬停目标用亮橙色对比度足够。这个功能的实现依赖前面keyToIndex映射。拥有{z,x,y}后查 Map 得到线段起点索引再通过操作 geometry 的 color attribute 将这四条边对应的八个顶点的颜色改变。如果不使用顶点色你也可以给 hover 的瓦片单独生成一个 Mesh 或独立 LineSegments但那会引入额外 draw call而且在高亮瓦片数量多时逻辑麻烦。顶点色方案最干净。为了不把 mousemove 事件处理绑得太频繁我用的是 rAF 驱动的“请求-检查-执行”模式鼠标事件只把最新坐标存入变量渲染循环里判断变量是否变化然后才更新探针和线框高亮。节流能有效避免地图移动时发生大量无意义的坐标反查。5. 接入运行时最省心的主流程组装方式5.1 DebugToolkit 的职责划分到第 5 节为止说的都是独立类真正往运行时里接的时候建议用一个聚合类DebugToolkit统一管理。它负责初始化 TileGridDebugLayer、cursor 探针面板、事件监听提供enable()和disable()方法。主流程里其他模块完全不需要感知 DebugToolkit 的存在。class DebugToolkit { private gridLayer new TileGridDebugLayer(); private probe new CursorProbe(); private enabled false; constructor(private viewer: MapRuntimeViewer) {} enable() { if (this.enabled) return; this.enabled true; this.gridLayer.attach(this.viewer.scene); this.probe.attach(this.viewer.canvas); // 监听缓存事件更新线框 this.viewer.cache.on(tiles-changed, () { this.gridLayer.markDirty(); }); } disable() { if (!this.enabled) return; this.enabled false; this.gridLayer.detach(); this.probe.detach(); } }用事件总线订阅tiles-changed是一个很稳的做法。瓦片缓存管理器每次变化后发出事件DebugToolkit 只负责在下一帧重绘网格。业务和调试始终通过事件解耦以后系统复杂了也不会出现调试工具和业务逻辑互相扯皮的情况。5.2 主流程完整执行链我把它接好之后一次完整的调试操作是这样的开启调试开关键盘按快捷键D。瓦片加载完成后DebugToolkit 收到缓存变化事件把当前活跃的 TileKey 线框画到场景中。鼠标在屏幕上移动探针实时计算当前射线与地面交点的世界坐标并显示经纬度和当前 zoom 下 TileKey。鼠标经过某块瓦片时这块瓦片的线框边缘立刻变成高亮色旁边颜色正常。如果某些瓦片请求失败能在线框层叠加的状态位里直接看到加载失败的瓦片范围会用红色描边突出显示地图上任何裂缝都会被网格线挡住问题一目了然。这套执行链其实特别适合做自动化回归你可以把鼠标坐标模拟到任意点然后断言探针返回的 TileKey 是否符合预期。我在本地试过用它去验证瓦片裁剪是否有边界误差几次就发现相机旋转到特定角度后边缘多加载了一层瓦片问题从几千行代码缩小到了视锥裁剪的 8 个角点计算里。5.3 一个能提升效率的视觉分层设计Debug 图层的视觉设计不能无所谓建议为不同 TileKey 状态分配固定颜色。加载完成用青色加载中用黄色失败用红色LOD 过渡中的父区瓦片用半透明深色。颜色逻辑不要让美术自由发挥必须固定在配置里。颜色信息可以放进线框的colorvertex attribute。我一般会准备一个keyStatus的 Map当瓦片加载状态改变时更新 status并将 map 里的颜色写回线框几何体。完全静态的线框一旦上了状态颜色Debug 能力就从“显示几何结构”升级成“显示数据结构”排查问题的速度会快一个数量级。这一点是我做了第四个瓦片功能后才悟出来的如果一开始就知道前面几篇调 LOD 的体验会舒服得多。6. 实测中遇到的典型问题排查顺序与修法6.1 探针结果和实际画面偏移cursor 探针最容易出的问题是“鼠标明明停在这个瓦片上面板却显示相邻瓦片”。我排查后发现绝大多数情况不是坐标换算错而是 NDC 计算时用了 canvas CSS 像素和缓冲像素混用。如果你做过多倍设备适配canvas 的width属性可能是 1024CSS 实际宽度是 512这时clientX / rect.width得出的比例是没问题的出问题的是拿 canvas.width 去当 rect.width 用导致整体比例放大 2 倍。统一使用getBoundingClientRect()拿 CSS 尺寸再按 buffer 尺寸换算比例即可解决。另一个容易忽略的点是相机矩阵未更新。如果你在前一帧修改了相机位置或旋转但探针射线在渲染循环前的更新时机过早看到的就是上一帧相机矩阵下的结果。探针更新一定要放在 camera.updateMatrixWorld 之后或者干脆放在最后一帧渲染结束后执行。否则画面和探针永远差一帧鼠标快速移动时误差尤其明显。6.2 线框闪烁与 LineWidth 失效线框紧贴瓦片地面时闪烁是因为深度冲突。最简单的方法是给线框抬高 0.01~0.05但这会带来新问题拉远视角后0.05 的高度几乎消失拉近俯视时0.05 又可能显得偏离地面。我目前的做法是每一帧根据相机到地图平面的距离动态设置线框 Y 坐标偏移量const offset distanceToGround * 0.002; gridLayer.setYOffset(offset);另一点是LineBasicMaterial.linewidth在很多浏览器环境里无效最大只能渲染 1px。如果想让 TileKey 线框在某些视角下更醒目就不要依赖 linewidth。可以把线框的 Y 轴位置抬高再叠加半透明面片或者直接改用更宽的二维轮廓绘制。个人实际调试时发现 1px 在 4K 屏上偏细但不影响判断瓦片位置故没有为线宽做额外方案。6.3 动态删瓦片时 Key 和顶点索引对不上这个问题最隐蔽。瓦片主动卸载后keyToIndex映射如果没跟着清理下一次某个新瓦片的 key 恰好与已删除 key 重复时线框会出现两条重叠边或高亮到错误瓦片。修法很简单任何 UpdateGrid 操作前先清空映射或者用引用计数保证同一个 key 在 Map 中唯一。我踩过几次之后已经养成习惯凡是 Debug 工具里存在 Map 映射的管理类统一以clear-and-rebuild为准性能不够再谈增量优化避免因为残留状态产生幻觉数据。6.4 多倍数屏下文字和网格密度失衡当图像缩放比是 2 时1px 线框会显得很细HUD 文字也可能发虚。坐标探针面板我不用 three.js 的 Sprite 来渲染而是用 HtmlOverlay 绝对定位在 canvas 外部这样能直接吃浏览器 CSS 的清晰渲染不会因为 WebGL 渲染管线导致文字锯齿。线框本身暂时可以接受细一些如果真需要清晰粗线建议用 gl_LINEWIDTH 扩展或者直接用几何条带模拟但日常调试通常不值得为这个增加复杂度。6.5 探针更新导致小程序/低端机发热鼠标移动事件频率远超帧率如果你每个 mousemove 事件里发生 raycast 坐标转换 UI 更新帧率必然被拖垮。低端机上更明显。我最终的方案是把探针更新收归到主循环的 rAF 中保证一帧最多只更新一次。另一个优化是 UI 文本不直接改 DOM而是把结果缓存成字符串只有内容变化时才写入节点避免频繁触发布局重排。最后再分享一个调试工具带给我的超预期价值这部分可能是第九篇里我最想对你说的。本来我以为 TileKey 线框和 cursor 坐标探针只是“排查 bug 用的烂尾工具”但实际用起来发现Debug 层本身会成为你设计瓦片系统的语言。当整个代码库里每个人都能把一个坐标说成“第 8 级 173/94 号瓦片的右上角”时讨论加载策略、讨论 LOD 切换、讨论缓存淘汰都不需要先在脑子里构建一个三维网格模型。后面我又把线框状态和瓦片加载时序录下来做回放很多偶发抖动问题不需要靠打断了一次回放就能定位到具体瓦片的生命周期。如果你也正在做类似的地图运行时我建议把这一层工具放在渲染核心之前铺好不要觉得它可有可无。