1. 当你的Mars3D地图“卡”住了：一次性能瓶颈的深度排查

最近在做一个智慧园区项目，需要在地图上展示几百栋建筑的标签。一开始用Mars3D的LabelEntity，效果挺好，文字清晰，样式也丰富。但随着数据量上来，问题就来了——页面首次加载时，浏览器直接“卡死”好几秒，鼠标转圈圈，客户那边配置差点的电脑，甚至直接提示页面无响应。测试同事毫不客气地把这归为“必须解决的BUG”，压力一下子就给到了我这里。

我一开始也纳闷，不就是几百个文字标签吗，能有多大开销？直到我打开浏览器的开发者工具，在Performance面板里跑了一次性能分析，真相才浮出水面。加载400多个带标签的实体时，JavaScript执行了将近5秒。更关键的是，火焰图里一个叫getImageData的方法，竟然独占鳌头，执行了超过2秒！这让我非常困惑：getImageData是Canvas的API，通常用于读取像素数据，我的标签明明是纯文本，Mars3D为什么要去操作Canvas呢？

为了验证猜想，我做了一个简单的对照实验。我把原本的BillboardEntity（包含图标和标签）换成了纯LabelEntity，结果加载时间减少了20%，但getImageData依然被调用。最后，我干脆把LabelEntity的style属性全部注释掉，再跑一次性能分析——getImageData的调用消失了。这下我彻底明白了：Mars3D在内部渲染文本标签时，无论你是否设置了背景、边框等样式，它最终都会将文本转换（“光栅化”）成一张图片（通常是Canvas）来交给WebGL渲染引擎处理。 对于每一个标签，这个“文本转图片”的过程都是同步进行的，当数量达到几百个时，在主线程上密集的Canvas绘图操作就成了性能瓶颈，直接导致页面卡顿。

这个发现让我有点哭笑不得。一方面，Mars3D（或者说其底层的Cesium）这么设计是为了保证跨平台渲染的一致性，毕竟WebGL原生不支持直接渲染矢量文字。但另一方面，这种“一刀切”的转换，在面对海量、静态的标签时，就显得非常低效。我们需要的，其实是一张“写好了文字的图片”，而不是每次渲染都现场“写字”。找到了病根，解决思路也就清晰了：绕过Mars3D内部的文本转图片流程，我们自己提前把带文字的图片准备好，直接以图片形式交给Mars3D渲染。

2. 自己动手，丰衣足食：用Canvas动态合成标签图片

既然问题出在动态生成图片上，那我们就自己来生成，并且只生成一次。我的项目里，每个建筑标签都是在同一个底图（di3.png）上叠加不同的建筑名称。这简直就是为Canvas量身定做的场景。

最初的实现思路很简单：在创建每个BillboardEntity之前，调用一个createImage函数。这个函数会创建一个离屏Canvas，先把底图画上去，再用fillText把建筑名称写到指定位置，最后把Canvas转换成DataURL（也就是base64格式的图片字符串），赋值给BillboardEntity的image属性。

function createImage(name) {
  const canvas = document.createElement("canvas");
  const ctx = canvas.getContext("2d");
  const img = new Image();
  
  // 注意：这里需要处理图片加载的异步性
  return new Promise((resolve) => {
    img.onload = () => {
      canvas.width = img.width;
      canvas.height = img.height;
      ctx.drawImage(img, 0, 0);
      // 设置文字样式
      ctx.font = "bold 20px Arial";
      ctx.textAlign = "center";
      ctx.textBaseline = "bottom";
      ctx.fillStyle = "#FFFFFF";
      // 在底图的特定位置绘制文字
      ctx.fillText(name, 220, 70);
      // 导出为DataURL
      resolve(canvas.toDataURL("image/png"));
    };
    img.src = "img/marker/di3.png";
  });
}

// 在添加实体时使用
async function addBuildingEntity(bsm, name, position) {
  const imageUrl = await createImage(name);
  const graphic = new mars3d.graphic.BillboardEntity({
    position: position,
    style: {
      image: imageUrl, // 使用我们生成的图片
      width: 300,
      height: 140,
      // ... 其他样式
    }
  });
  graphicLayer.addGraphic(graphic);
}

这个方案一上线，效果立竿见影。再次进行性能分析，那长达2秒多的getImageData调用彻底不见了，页面加载时间从近5秒降到了1秒以内，实现了“秒开”。这里的关键在于，我们将数百次“文本绘制+光栅化”的串行操作，变成了数百次“图片解码+渲染”的并行（或优化后）操作。 浏览器和GPU对图片渲染的优化程度远高于动态Canvas绘图。

但是，很快我又发现了新问题。每次刷新页面，这400多张图片都要重新生成一次。虽然不卡了，但每次打开页面，CPU使用率都会有一个短暂的飙升，网络不好的时候，底图加载也可能成为新的瓶颈。对于配置较低的客户端机器，这仍然是一种不必要的消耗。我们需要一个“记忆”机制，让浏览器记住这些已经生成过的图片。

3. 给浏览器装个“硬盘”：引入IndexedDB客户端缓存

想到缓存，你可能会先想到localStorage或sessionStorage。但它们的存储空间通常只有5-10MB，对于几百张可能几十KB甚至上百KB的PNG图片base64字符串来说，容量很快会捉襟见肘。而IndexedDB是浏览器端的“数据库”，存储空间大得多（通常是硬盘空间的50%），非常适合存储这类结构不复杂但体积较大的二进制数据（Blob）或字符串。

我的缓存策略设计如下：

1. 唯一键生成：每张图片的缓存键由“图层类型+建筑ID（bsm）+建筑名称”等要素拼接而成，确保唯一性。
2. 三级缓存查询：
   • 内存缓存（最快）：用一个全局对象（如const imageCache = {}）存储当前会话中已生成的图片URL，避免同一页面内重复生成。
   • IndexedDB缓存（次之）：页面刷新后，从IndexedDB中查找是否有该键对应的图片数据。
   • 动态生成（最后）：如果前两级都没有命中，则调用createImage函数生成新图片，并同时存入内存缓存和IndexedDB。

这里我推荐使用localForage这个库来操作IndexedDB，它提供了类似localStorage的简单API（getItem, setItem），但背后自动适配了IndexedDB、WebSQL等存储引擎，省去了直接操作IndexedDB繁琐的事务（Transaction）和游标（Cursor）代码。

下面是升级后的核心代码：

import localforage from 'localforage';

// 配置localforage使用IndexedDB
localforage.config({
  driver: localforage.INDEXEDDB,
  name: 'mars3d-cache',
  version: 1.0,
  storeName: 'label_images', // 存储仓库名
});

const memoryCache = {}; // 内存缓存

async function getCachedLabelImage(layerType, bsm, name, baseImageUrl) {
  const cacheKey = `${layerType}-${bsm}-${name}`;
  
  // 1. 检查内存缓存
  if (memoryCache[cacheKey]) {
    console.log(`[缓存] 内存命中: ${cacheKey}`);
    return memoryCache[cacheKey];
  }
  
  // 2. 检查IndexedDB缓存
  try {
    const cachedData = await localforage.getItem(cacheKey);
    if (cachedData) {
      // 可选：这里可以添加缓存有效性验证，比如对比底图版本、文字样式版本等
      console.log(`[缓存] IndexedDB命中: ${cacheKey}`);
      memoryCache[cacheKey] = cachedData; // 回填到内存
      return cachedData;
    }
  } catch (error) {
    console.warn('读取IndexedDB缓存失败:', error);
    // 降级处理，继续生成
  }
  
  // 3. 缓存未命中，动态生成
  console.log(`[缓存] 未命中，开始生成: ${cacheKey}`);
  const imageDataUrl = await createImage(name, baseImageUrl);
  
  // 4. 存入缓存
  memoryCache[cacheKey] = imageDataUrl;
  try {
    await localforage.setItem(cacheKey, imageDataUrl);
  } catch (error) {
    console.warn('写入IndexedDB缓存失败:', error);
    // 忽略写入错误，至少内存缓存已更新
  }
  
  return imageDataUrl;
}

// 修改后的创建实体函数
async function addBuildingEntityWithCache(bsm, name, position) {
  const layerType = 'building';
  const baseImageUrl = 'img/marker/di3.png';
  
  const imageUrl = await getCachedLabelImage(layerType, bsm, name, baseImageUrl);
  
  const graphic = new mars3d.graphic.BillboardEntity({
    id: bsm,
    position: position,
    style: {
      image: imageUrl,
      // ... 其他样式
    }
  });
  graphicLayer.addGraphic(graphic);
}

引入这套缓存机制后，首次打开页面，因为要生成并存储所有图片，速度和我们第一次优化后差不多。但第二次及以后打开页面，性能体验就有了质的飞跃——图片几乎瞬间从本地数据库加载完毕，地图渲染流畅无比。这相当于把大量的计算成本从“每次加载”转移到了“首次加载”，极大地提升了重复访问的用户体验。

4. 深入优化：从能用，到好用且健壮

基本的动态生成和缓存已经解决了卡顿问题，但在实际生产环境中，我们还需要考虑更多细节，让方案更健壮、更高效。

4.1 缓存更新与失效策略

数据不是一成不变的。如果后台修改了某个建筑的名称，或者更新了底图样式，我们的缓存就需要更新。我设计的策略是在缓存键中融入“版本号”或“数据指纹”。例如，在创建缓存键时，不仅包含bsm和name，还加入一个从服务器获取的、代表数据版本的hash值。

// 假设从接口获取了数据版本哈希
const dataVersionHash = await fetchDataVersion();
const cacheKey = `${layerType}-${bsm}-${name}-${dataVersionHash}`;

当后台数据更新时，dataVersionHash改变，生成的缓存键自然不同，旧缓存不会被命中，系统会生成新的图片并缓存。对于如何清理旧的、无效的缓存数据，可以定期（如每周）或在应用启动时执行一个简单的清理任务，删除所有不包含最新版本哈希的缓存项。

4.2 Canvas绘制的性能细节

Canvas绘图本身也有优化空间。比如，确保底图加载完成后再进行绘制，避免绘制空白或错误的图片。上面代码中使用的onload回调或async/await就是为了保证这一点。另外，对于固定尺寸的图片，可以精确设置canvas.width和canvas.height，避免不必要的缩放和内存占用。文字渲染方面，如果字体样式固定，可以考虑将ctx.font等设置提前，避免在循环中重复设置。

4.3 内存管理与大数量级处理

虽然用了缓存，但如果标签数量达到数千甚至上万，内存中的memoryCache对象可能会过大。我们可以实现一个简单的LRU（最近最少使用）策略，限制内存缓存的数量，将最不常用的图片从内存中移除，但保留在IndexedDB中。对于极端情况，还可以考虑“分页”或“按需加载”策略，只生成和缓存当前视图范围内的标签图片。

4.4 错误处理与降级方案

网络或存储都可能出错。我们的代码需要健壮性。在getCachedLabelImage函数中，我对localforage.getItem和setItem进行了try-catch包裹。即使IndexedDB操作失败（例如用户禁用或存储空间满），程序也能降级到动态生成模式，保证核心功能的可用性，同时将错误信息记录到日志，方便排查。

5. 效果对比与方案总结

为了更直观地展示优化效果，我整理了优化前后的核心指标对比：

对比项	优化前 (原生LabelEntity)	优化后 (Canvas生成 + IndexedDB缓存)
首次加载时间	~5000ms (严重卡顿)	~800ms (包含生成与存储)
二次加载时间	~5000ms (无改善)	< 100ms (从本地缓存读取)
主线程阻塞	严重，getImageData耗时2s+	轻微，主要为异步图片解码
CPU占用峰值	高且持续时间长	首次高，后续极低
内存占用	较低	略高（存储了图片数据），但可控
适用场景	标签数量少 (<50)	标签数量多 (>100)，且内容相对静态
开发复杂度	低，使用Mars3D原生API	中，需自行处理Canvas与缓存逻辑

从表格可以清晰看到，这个优化方案用一定的开发复杂度和客户端存储空间，换来了渲染性能的数量级提升。它特别适合那些标签文本固定、样式统一、且数量庞大的场景，比如智慧城市中的楼宇标注、电网系统中的设备标签、物流地图中的仓库点位等。

踩过这个坑，我最大的体会是：框架的便利性有时会掩盖底层的性能成本。Mars3D的LabelEntity API非常友好，让我们可以像设置DOM样式一样轻松地配置文字标签。但在追求极致性能，尤其是面对海量数据时，我们不得不深入一层，去理解框架背后的渲染机制（文本转图片），并亲手构建更高效的替代方案（预生成图片+缓存）。这个过程虽然麻烦，但带来的用户体验提升是实实在在的。现在，即使在地图上展示上千个标签，页面也能流畅加载和交互，客户那边的低配电脑也不再抱怨卡顿了。技术方案的选型，永远需要在开发效率、运行性能和用户体验之间找到最佳的平衡点。