简介面向Cesium开发者的POI点聚合源码包解决原生Cesium缺少primitive聚合功能、常需修改EntityCluster源码的问题。方案利用DistanceDisplayCondition属性按typename字段的层级关系动态计算显隐视距分为远、中、近三档无需改动Cesium内部机制。压缩包共2个文件含1个HTML演示页面和1个inscode代码文件整体仅4KB结构精简便于集成。已有78人浏览学习适合WebGIS开发人员与三维可视化学习者参考。代码中_clustering方法负责视距计算_add方法应用distanceDisplayCondition控制显示可迁移至大规模POI渲染场景结合多级分类还能实现精细类型远景隐藏、粗分类近景展示的层级聚合效果从而减少遮挡、提升渲染效率。 提到Cesium的POI点聚合干GIS可视化这行的朋友应该都体会过那种痛几千个点位往场景里一丢旋转缩放直接掉帧几十万POI更是连浏览器都差点带不动。点聚合就是专门治这个毛病的思路把空间上离得近的点在低层级合并成一个带数量统计的聚合点视野拉近了再逐个铺开渲染压力小数据信息也不丢。这篇文章我基于自己实际项目里的踩坑和调优经验把Cesium里POI点聚合的完整实现方法、核心参数逻辑、代码细节以及大促场景下的性能优化方案一次性讲透。不管你是刚上手Cesium的新人还是已经被海量点位折磨过一轮的老手这篇都能给你一套能直接抄作业的落地方案。1. 需求拆解与方案选型思路1.1 点聚合到底解决了什么问题POI点数据在LBS类项目里太常见了餐饮门店、停车场、景区景点、设备分布本质都是坐标点加业务属性。问题在于数量一上来直接渲染全部点位的代价非常高。Cesium里每创建一个Entity本质上就是往场景图里塞一个独立实体对象Draw Call、GPU提交、拾取计算都会随之增长。一万个Entity差不多就能感觉到明显的拖拽卡顿十万个基本告别流畅交互。聚合的核心思想是“按当前视野动态合并”。相机高度高的时候把邻近点合并成一个大点上面直接标“256”这种数量用户一眼就知道这块有多少POI镜头拉低聚合点自动散开成具体的POI图标。这不仅仅是性能优化也是交互体验层面的需求否则一堆图标叠在一起根本没法点。还有一个常被忽略的点聚合能显著降低网络和内存压力。配合后端做按视野范围的数据裁剪后前端实际承载的实体数可以控制在一个稳定区间不会因为地图缩放导致内存暴涨。1.2 主流实现方案横向对比我在几个项目里分别试过三种路线各有各的适用场景简单总结如下方案核心原理性能表现实现成本适合场景Entity clustering基于EntityCluster自动聚合Cesium官方API中适合万级以下低代码量小大多数业务POI展示快速上线Primitive自研聚合用网格分桶算法自行合并再用PointPrimitive/Billboard渲染高可承载十万级以上高需自己写聚合逻辑海量点位、对性能要求极高的场景第三方库叠加如supercluster做前端聚合再喂给Cesium中高依赖算法效率中需要复杂聚合策略如按权重、按行政区聚合大部分项目我会建议直接走第一种。Cesium从1.60版本开始对EntityCluster的封装就比较成熟了官方提供的聚类事件、聚合样式覆盖接口能够满足绝大多数展示需求。只有在POI数量真的大到 Entity 层级已经撑不住时才需要切换到Primitive自研路线。选型的核心判断依据是数据量级。如果你的点位在一两万以内老老实实用Entity clustering开发效率高后期维护成本低只有明确测出Entity方案在目标低端设备上帧率跌破阈值再考虑用Primitive方案去压榨性能。2. EntityCluster官方聚合机制拆解2.1 核心参数pixelRange和minimumClusterSize的调参逻辑EntityCluster的实现原理是把可视范围内的实体通过屏幕空间投影根据像素距离做聚类。这里有两个参数直接决定聚合效果分别是pixelRange和minimumClusterSize。pixelRange表示判断点与点相距多少像素以内就归为同一聚合。默认值是80但实际项目中我通常会在30到60之间选。值设太大聚合会很激进相机稍微拉高一点整片区域就变成一个点用户想定位具体的某个POI反而麻烦值设太小聚合效果不明显性能问题依旧。一般如果POI在城市里比较密集我会先用60起步再根据实际预览效果微调。minimumClusterSize表示最少多少个点才触发聚合默认值是2也就是两个点只要靠得够近就会被聚合。如果业务上希望至少5个POI才算一个“热点区域”可以把这个参数往上调避免稀疏散落的点位被强行合并干扰用户判断。手动配置的代码片段如下dataSource.clustering.enabled true; dataSource.clustering.pixelRange 50; dataSource.clustering.minimumClusterSize 3;注意调整这两个参数后聚合结果的变化是即时的不需要重建数据源。这在调试阶段非常方便打开浏览器的开发者工具直接在控制台改参数看效果就行。2.2 clusterEvent回调与聚合实体的处理细节当视野变化导致聚合状态改变时Cesium会触发clusterEvent回调协议参数带出两个关键对象一个是参与聚合的实体数组另一个是当前生成的聚合Entity。这个回调是自定义聚合样式的入口也是实现点击交互的关键。dataSource.clustering.clusterEvent.addEventListener( function (clusteredEntities, cluster) { const count clusteredEntities.length; cluster.label.text count.toString(); cluster.label.font bold 14px sans-serif; cluster.label.fillColor Cesium.Color.WHITE; cluster.billboard.image count 100 ? /images/cluster-large.png : /images/cluster-default.png; } );这段代码可以做很多事情但有几个细节需要注意。第一cluster参数本身是一个Entity对象所以你可以直接给它挂properties把数量甚至聚合点列表存进去方便后续点击拾取时使用。第二回调触发频率很频繁只要聚合发生变化就会进入所以里面的逻辑要尽量轻量不要做复杂的DOM操作或者计算密集的任务。第三聚合实体的样式默认会走scene.clusterBillboard和scene.clusterLabel如果你希望所有聚合点统一用一个样式直接设置这两个集合里的属性也可以。3. 从零到一POI点聚合代码落地3.1 数据准备与数据源创建先说明一下数据准备。POI数据我通常采用GeoJSON格式传入因为Cesium的GeoJsonDataSource可以直接加载省去写遍历代码的功夫。如果业务数据是后端返回的JSON数组那么自己组装Entity也很快。// 创建聚合数据源 const poiDataSource new Cesium.CustomDataSource(poi-layer); const pois await fetch(/api/pois).then(res res.json()); pois.forEach(function (item) { poiDataSource.entities.add({ position: Cesium.Cartesian3.fromDegrees(item.lng, item.lat), id: item.id, name: item.name, // 业务属性随手挂上去 properties: { phone: item.phone, category: item.category }, billboard: { image: /images/poi-icon.png, width: 32, height: 32 } }); }); viewer.dataSources.add(poiDataSource);这里要提醒一点如果想用官方聚合实体类型尽量用Entity不要用PointPrimitive。虽然Primitive在性能上更优但EntityCluster的聚合机制是建立在Entity体系上的Primitive不参与自动聚类。3.2 启用聚合与核心参数配置数据源创建好之后直接启用clustering属性就可以实现聚合但参数需要根据地图的初始相机高度来调节。如果初始视野是全市级别pixelRange可以适当加大如果初始视野是一个区县建议从较小值开始。poiDataSource.clustering.enabled true; poiDataSource.clustering.pixelRange 50; poiDataSource.clustering.minimumClusterSize 2;关于pixelRange与缩放的关系我有个经验值。默认视野高度在城市级时pixelRange在50到60之间整体观感最自然当需要同时显示跨省数据时建议开放一个可拖动的滑块给用户自己调节毕竟每个人对“聚合粒度”的感知不同。3.3 自定义聚合图标和数量气泡默认的聚合样式是一个蓝色的圆形泡泡加白色数字实际业务里难免要改成符合品牌视觉的样式。Cesium支持在clusterEvent回调里直接替换聚合点的图片和文字样式也可以提前配置scene上的聚合渲染集合。我项目里最常用的做法是这样viewer.scene.clusterBillboard new Cesium.BillboardCollection(viewer.scene); viewer.scene.clusterLabel new Cesium.LabelCollection(viewer.scene);然后在clusterEvent回调里只改label文本就行。这种方式比在回调里逐帧修改聚合Entity的billboard和label要更高效因为聚合Entity本质上就是通过这两个集合渲染的直接改集合的样式聚合点的表现会实时同步。但有一个坑需要注意直接给聚合Entity设置label.text时如果数量很大文字溢出气泡图片边界会显得很丑。我的处理是动态计算字体大小数量越大字体相对缩小const count clusteredEntities.length; cluster.label.font count 1000 ? bold 10px sans-serif : count 500 ? bold 12px sans-serif : bold 14px sans-serif;3.4 聚合体的点击交互实现很多场景下用户点聚合点应该看到这个区域的POI列表或者自动放大到该区域。这里我会用ScreenSpaceEventHandler监听左键通过scene.pick拾取到聚合Entity再读取之前挂载的properties信息。const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (Cesium.defined(picked) Cesium.defined(picked.id)) { const entity picked.id; // 判断是聚合点还是普通POI if (Cesium.defined(entity.properties) entity.properties.isCluster) { const count entity.properties.count; const center entity.position.getValue(viewer.clock.currentTime); console.log(聚合数量: count, 中心点: center); // 可选直接飞到聚合区域 viewer.camera.zoomTo(entity, 1.5); } } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);这里有经验分享在clusterEvent里给聚合Entity挂属性时不要使用entity.properties直接赋值因为Cesium的Entity.properties类型是PropertyBag支持直接挂JSON字段但是要注意命名不要和Cesium内置属性冲突。我一般统一加一个isCluster布尔标识避免点击时区分不了聚合点和普通POI。4. 大数据量场景下的性能调优实录4.1 数据抽稀与分级加载即便有了聚合前端一次加载超过十万个Entity初始化的压力还是很大。解决思路是分级加载按照相机高度把数据分成多个层级低层级只加载抽稀后的粗粒度数据高层级再加载全量数据。后端在做数据下发时可以按网格抽稀比如每一个网格最多返回固定数量POI。前端在相机高度变化触发camera.moveEnd事件后根据当前高度重新加载对应层级的POI数据。这部分要配合一个简单的LOD策略function getDataLevel(cameraHeight) { if (cameraHeight 30000) return level3; // 全国级 if (cameraHeight 8000) return level2; // 地市级 return level1; // 区县级 }这个策略不需要太复杂关键是避免每个层级都重新加载全量数据。我遇到过一个差点上线的项目就是因为每次moveEnd都请求全量POI导致用户每次缩放地图都会看到一大片图标闪烁。后来把数据改成按level分片下发问题直接解决。4.2 Primitive方案与Entity方案的取舍如果数据规模真的到了几十万Entity聚合也扛不住时就得考虑Primitive自研方案。核心逻辑是自己实现一个屏幕空间网格聚合把投影坐标分桶每桶只有当聚合数量达到阈值时才生成一个PointPrimitive或Billboard。function buildClusters(points, gridSize, viewer) { const clusters new Map(); points.forEach(pt { const pos Cesium.Cartesian3.fromDegrees(pt.lng, pt.lat); const screenPos Cesium.SceneTransforms.worldToWindowCoordinates(viewer.scene, pos); if (!screenPos) return; const key ${Math.floor(screenPos.x / gridSize)}-${Math.floor(screenPos.y / gridSize)}; if (!clusters.has(key)) clusters.set(key, []); clusters.get(key).push(pt); }); // 遍历clusters生成聚合Primitive clusters.forEach((pts, key) { if (pts.length 2) { // 计算该桶中心位置生成聚合点 } else { // 散点直接渲染 } }); }这种做法的最大好处是彻底摆脱Entity开箱即用的便利性转而使用Primitive的高渲染效率。但代价也不小聚合计算需要自己写缩放重算逻辑需要自己处理相机移动时还要考虑如何平滑更新聚合状态。除非数据量确实很大否则我通常不推荐一上来就all in Primitive把简单问题复杂化反而会增加维护成本。4.3 实测调优效果对比我在一个门店POI项目里做了一组对照实验数据量三万点设备是普通办公笔记本。纯Entity直接渲染初始化耗时约4秒相机拖拽时帧率最低掉到18fpsCPU占用经常飙到90%以上。开启EntityCluster聚合后初始加载降到了2秒左右正常交互帧率稳定在35fps以上CPU占用降了一半。后来又单独用Primitive自研方案测试了十万点场景初始化耗时控制在1秒内交互帧率基本稳定在50fps以上。代价是开发量多出了将近两个工作日而且聚合粒度的交互表现需要额外调优。综合来看两三万点以下用官方聚合方案完全足够超过十万点时再考虑走上层路线。中间的量级可以尝试混合方案Entity聚合用于展示Primitive用于后台计算热点密度。5. 常见问题排查速查表POI点聚合看着简单实际落地时坑不少。我把这几年遇到的高频问题整理成了一张表方便兄弟们排查问题现象可能原因处理方案聚合点显示为默认蓝色样式设置不生效clusterEvent里修改的是聚合Entity但聚合样式被scene.clusterBillboard覆盖直接修改scene.clusterBillboard和scene.clusterLabel的样式点击聚合点没有响应聚合实体可能不是通过id拾取拾取结果里id为空检查pick返回对象改用picked.primitive处理或确认聚合Entity已挂properties聚合后普通POI的billboard图标消失聚合生效时被聚合的Entity隐藏是正常行为不要尝试在聚合事件里强制显示原Entity否则会导致渲染混乱相机拉低后聚合散开很慢或闪跳数据量过大或聚合回调里做了耗时操作精简clusterEvent逻辑必要时用requestAnimationFrame做节流pixelRange值一样但不同区域聚合效果差异很大不同区域POI密度差异大单一参数难免顾此失彼按需要把聚合参数做成动态的或者按网格区域差异化配置聚合点数量显示为0或不刷新聚合Entity的label文本更新时机不对确保在clusterEvent里对_cluster.label.text赋值而非创建时设置一次地图居中后聚合错位相机变换时聚合位置未更新检查是否在相机移动结束后调用了dataSource.clustering.update()或升级Cesium版本其中点击聚合点没反应是最多人踩的坑。实际上是很多新手把聚合Entity当成普通Entity去看待直接在click监听里用picked.id.name取数据结果发现什么都没有。聚合Entity默认没有name它的信息主要靠你手动在clusterEvent里挂载这一步容易漏。还有一个细节容易忽略viewer.scene.pick在聚合点上的返回结果里picked.id有时可能不是Entity而是一个内部对象。稳妥的做法是在pick后先判断picked.id instanceof Cesium.Entity再做后续处理。6. 写在最后我这两年的一线体会Cesium的POI点聚合表面上是几个参数开关的事真正铺开做的时候才会发现里面的门道不少。我给新人的建议是第一步先把官方EntityCluster跑通理解pixelRange和minimumClusterSize的含义第二步再用clusterEvent去自定义样式和交互最后才考虑性能边界优化数据加载和渲染管线。这个顺序能让你少走很多弯路。我之前吃过一次亏项目上线前测试时把pixelRange调成了5结果POI密度稍高的区域几乎看不出聚合效果用户反馈地图上全是图标又卡又乱。后来反思了一下聚合参数一定要结合真实业务数据来做验证不能拍脑袋定值。还有个一直在用的小技巧把聚合参数开放成调试面板里的可调项部署到测试环境后让产品经理自己拖滑块调调到满意了再把数值固化进配置里。这样既能快速收敛参数也让团队里每个人对聚合效果有了直观认识。如果刚接触Cesium建议直接从最新的稳定版开始老版本里一些聚合相关的bug在新版中修了不少。文档方面Cesium官方示例的Clustering就是很好的学习起点把示例代码跑通之后再叠加自己的业务逻辑比对着网上零散代码抄要靠谱得多。本文还有配套的精品资源点击获取 Cesium POI点聚合实战：从EntityCluster到大数据性能优化
简介面向Cesium开发者的POI点聚合源码包解决原生Cesium缺少primitive聚合功能、常需修改EntityCluster源码的问题。方案利用DistanceDisplayCondition属性按typename字段的层级关系动态计算显隐视距分为远、中、近三档无需改动Cesium内部机制。压缩包共2个文件含1个HTML演示页面和1个inscode代码文件整体仅4KB结构精简便于集成。已有78人浏览学习适合WebGIS开发人员与三维可视化学习者参考。代码中_clustering方法负责视距计算_add方法应用distanceDisplayCondition控制显示可迁移至大规模POI渲染场景结合多级分类还能实现精细类型远景隐藏、粗分类近景展示的层级聚合效果从而减少遮挡、提升渲染效率。 提到Cesium的POI点聚合干GIS可视化这行的朋友应该都体会过那种痛几千个点位往场景里一丢旋转缩放直接掉帧几十万POI更是连浏览器都差点带不动。点聚合就是专门治这个毛病的思路把空间上离得近的点在低层级合并成一个带数量统计的聚合点视野拉近了再逐个铺开渲染压力小数据信息也不丢。这篇文章我基于自己实际项目里的踩坑和调优经验把Cesium里POI点聚合的完整实现方法、核心参数逻辑、代码细节以及大促场景下的性能优化方案一次性讲透。不管你是刚上手Cesium的新人还是已经被海量点位折磨过一轮的老手这篇都能给你一套能直接抄作业的落地方案。1. 需求拆解与方案选型思路1.1 点聚合到底解决了什么问题POI点数据在LBS类项目里太常见了餐饮门店、停车场、景区景点、设备分布本质都是坐标点加业务属性。问题在于数量一上来直接渲染全部点位的代价非常高。Cesium里每创建一个Entity本质上就是往场景图里塞一个独立实体对象Draw Call、GPU提交、拾取计算都会随之增长。一万个Entity差不多就能感觉到明显的拖拽卡顿十万个基本告别流畅交互。聚合的核心思想是“按当前视野动态合并”。相机高度高的时候把邻近点合并成一个大点上面直接标“256”这种数量用户一眼就知道这块有多少POI镜头拉低聚合点自动散开成具体的POI图标。这不仅仅是性能优化也是交互体验层面的需求否则一堆图标叠在一起根本没法点。还有一个常被忽略的点聚合能显著降低网络和内存压力。配合后端做按视野范围的数据裁剪后前端实际承载的实体数可以控制在一个稳定区间不会因为地图缩放导致内存暴涨。1.2 主流实现方案横向对比我在几个项目里分别试过三种路线各有各的适用场景简单总结如下方案核心原理性能表现实现成本适合场景Entity clustering基于EntityCluster自动聚合Cesium官方API中适合万级以下低代码量小大多数业务POI展示快速上线Primitive自研聚合用网格分桶算法自行合并再用PointPrimitive/Billboard渲染高可承载十万级以上高需自己写聚合逻辑海量点位、对性能要求极高的场景第三方库叠加如supercluster做前端聚合再喂给Cesium中高依赖算法效率中需要复杂聚合策略如按权重、按行政区聚合大部分项目我会建议直接走第一种。Cesium从1.60版本开始对EntityCluster的封装就比较成熟了官方提供的聚类事件、聚合样式覆盖接口能够满足绝大多数展示需求。只有在POI数量真的大到 Entity 层级已经撑不住时才需要切换到Primitive自研路线。选型的核心判断依据是数据量级。如果你的点位在一两万以内老老实实用Entity clustering开发效率高后期维护成本低只有明确测出Entity方案在目标低端设备上帧率跌破阈值再考虑用Primitive方案去压榨性能。2. EntityCluster官方聚合机制拆解2.1 核心参数pixelRange和minimumClusterSize的调参逻辑EntityCluster的实现原理是把可视范围内的实体通过屏幕空间投影根据像素距离做聚类。这里有两个参数直接决定聚合效果分别是pixelRange和minimumClusterSize。pixelRange表示判断点与点相距多少像素以内就归为同一聚合。默认值是80但实际项目中我通常会在30到60之间选。值设太大聚合会很激进相机稍微拉高一点整片区域就变成一个点用户想定位具体的某个POI反而麻烦值设太小聚合效果不明显性能问题依旧。一般如果POI在城市里比较密集我会先用60起步再根据实际预览效果微调。minimumClusterSize表示最少多少个点才触发聚合默认值是2也就是两个点只要靠得够近就会被聚合。如果业务上希望至少5个POI才算一个“热点区域”可以把这个参数往上调避免稀疏散落的点位被强行合并干扰用户判断。手动配置的代码片段如下dataSource.clustering.enabled true; dataSource.clustering.pixelRange 50; dataSource.clustering.minimumClusterSize 3;注意调整这两个参数后聚合结果的变化是即时的不需要重建数据源。这在调试阶段非常方便打开浏览器的开发者工具直接在控制台改参数看效果就行。2.2 clusterEvent回调与聚合实体的处理细节当视野变化导致聚合状态改变时Cesium会触发clusterEvent回调协议参数带出两个关键对象一个是参与聚合的实体数组另一个是当前生成的聚合Entity。这个回调是自定义聚合样式的入口也是实现点击交互的关键。dataSource.clustering.clusterEvent.addEventListener( function (clusteredEntities, cluster) { const count clusteredEntities.length; cluster.label.text count.toString(); cluster.label.font bold 14px sans-serif; cluster.label.fillColor Cesium.Color.WHITE; cluster.billboard.image count 100 ? /images/cluster-large.png : /images/cluster-default.png; } );这段代码可以做很多事情但有几个细节需要注意。第一cluster参数本身是一个Entity对象所以你可以直接给它挂properties把数量甚至聚合点列表存进去方便后续点击拾取时使用。第二回调触发频率很频繁只要聚合发生变化就会进入所以里面的逻辑要尽量轻量不要做复杂的DOM操作或者计算密集的任务。第三聚合实体的样式默认会走scene.clusterBillboard和scene.clusterLabel如果你希望所有聚合点统一用一个样式直接设置这两个集合里的属性也可以。3. 从零到一POI点聚合代码落地3.1 数据准备与数据源创建先说明一下数据准备。POI数据我通常采用GeoJSON格式传入因为Cesium的GeoJsonDataSource可以直接加载省去写遍历代码的功夫。如果业务数据是后端返回的JSON数组那么自己组装Entity也很快。// 创建聚合数据源 const poiDataSource new Cesium.CustomDataSource(poi-layer); const pois await fetch(/api/pois).then(res res.json()); pois.forEach(function (item) { poiDataSource.entities.add({ position: Cesium.Cartesian3.fromDegrees(item.lng, item.lat), id: item.id, name: item.name, // 业务属性随手挂上去 properties: { phone: item.phone, category: item.category }, billboard: { image: /images/poi-icon.png, width: 32, height: 32 } }); }); viewer.dataSources.add(poiDataSource);这里要提醒一点如果想用官方聚合实体类型尽量用Entity不要用PointPrimitive。虽然Primitive在性能上更优但EntityCluster的聚合机制是建立在Entity体系上的Primitive不参与自动聚类。3.2 启用聚合与核心参数配置数据源创建好之后直接启用clustering属性就可以实现聚合但参数需要根据地图的初始相机高度来调节。如果初始视野是全市级别pixelRange可以适当加大如果初始视野是一个区县建议从较小值开始。poiDataSource.clustering.enabled true; poiDataSource.clustering.pixelRange 50; poiDataSource.clustering.minimumClusterSize 2;关于pixelRange与缩放的关系我有个经验值。默认视野高度在城市级时pixelRange在50到60之间整体观感最自然当需要同时显示跨省数据时建议开放一个可拖动的滑块给用户自己调节毕竟每个人对“聚合粒度”的感知不同。3.3 自定义聚合图标和数量气泡默认的聚合样式是一个蓝色的圆形泡泡加白色数字实际业务里难免要改成符合品牌视觉的样式。Cesium支持在clusterEvent回调里直接替换聚合点的图片和文字样式也可以提前配置scene上的聚合渲染集合。我项目里最常用的做法是这样viewer.scene.clusterBillboard new Cesium.BillboardCollection(viewer.scene); viewer.scene.clusterLabel new Cesium.LabelCollection(viewer.scene);然后在clusterEvent回调里只改label文本就行。这种方式比在回调里逐帧修改聚合Entity的billboard和label要更高效因为聚合Entity本质上就是通过这两个集合渲染的直接改集合的样式聚合点的表现会实时同步。但有一个坑需要注意直接给聚合Entity设置label.text时如果数量很大文字溢出气泡图片边界会显得很丑。我的处理是动态计算字体大小数量越大字体相对缩小const count clusteredEntities.length; cluster.label.font count 1000 ? bold 10px sans-serif : count 500 ? bold 12px sans-serif : bold 14px sans-serif;3.4 聚合体的点击交互实现很多场景下用户点聚合点应该看到这个区域的POI列表或者自动放大到该区域。这里我会用ScreenSpaceEventHandler监听左键通过scene.pick拾取到聚合Entity再读取之前挂载的properties信息。const handler new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas); handler.setInputAction(function (movement) { const picked viewer.scene.pick(movement.position); if (Cesium.defined(picked) Cesium.defined(picked.id)) { const entity picked.id; // 判断是聚合点还是普通POI if (Cesium.defined(entity.properties) entity.properties.isCluster) { const count entity.properties.count; const center entity.position.getValue(viewer.clock.currentTime); console.log(聚合数量: count, 中心点: center); // 可选直接飞到聚合区域 viewer.camera.zoomTo(entity, 1.5); } } }, Cesium.ScreenSpaceEventType.LEFT_CLICK);这里有经验分享在clusterEvent里给聚合Entity挂属性时不要使用entity.properties直接赋值因为Cesium的Entity.properties类型是PropertyBag支持直接挂JSON字段但是要注意命名不要和Cesium内置属性冲突。我一般统一加一个isCluster布尔标识避免点击时区分不了聚合点和普通POI。4. 大数据量场景下的性能调优实录4.1 数据抽稀与分级加载即便有了聚合前端一次加载超过十万个Entity初始化的压力还是很大。解决思路是分级加载按照相机高度把数据分成多个层级低层级只加载抽稀后的粗粒度数据高层级再加载全量数据。后端在做数据下发时可以按网格抽稀比如每一个网格最多返回固定数量POI。前端在相机高度变化触发camera.moveEnd事件后根据当前高度重新加载对应层级的POI数据。这部分要配合一个简单的LOD策略function getDataLevel(cameraHeight) { if (cameraHeight 30000) return level3; // 全国级 if (cameraHeight 8000) return level2; // 地市级 return level1; // 区县级 }这个策略不需要太复杂关键是避免每个层级都重新加载全量数据。我遇到过一个差点上线的项目就是因为每次moveEnd都请求全量POI导致用户每次缩放地图都会看到一大片图标闪烁。后来把数据改成按level分片下发问题直接解决。4.2 Primitive方案与Entity方案的取舍如果数据规模真的到了几十万Entity聚合也扛不住时就得考虑Primitive自研方案。核心逻辑是自己实现一个屏幕空间网格聚合把投影坐标分桶每桶只有当聚合数量达到阈值时才生成一个PointPrimitive或Billboard。function buildClusters(points, gridSize, viewer) { const clusters new Map(); points.forEach(pt { const pos Cesium.Cartesian3.fromDegrees(pt.lng, pt.lat); const screenPos Cesium.SceneTransforms.worldToWindowCoordinates(viewer.scene, pos); if (!screenPos) return; const key ${Math.floor(screenPos.x / gridSize)}-${Math.floor(screenPos.y / gridSize)}; if (!clusters.has(key)) clusters.set(key, []); clusters.get(key).push(pt); }); // 遍历clusters生成聚合Primitive clusters.forEach((pts, key) { if (pts.length 2) { // 计算该桶中心位置生成聚合点 } else { // 散点直接渲染 } }); }这种做法的最大好处是彻底摆脱Entity开箱即用的便利性转而使用Primitive的高渲染效率。但代价也不小聚合计算需要自己写缩放重算逻辑需要自己处理相机移动时还要考虑如何平滑更新聚合状态。除非数据量确实很大否则我通常不推荐一上来就all in Primitive把简单问题复杂化反而会增加维护成本。4.3 实测调优效果对比我在一个门店POI项目里做了一组对照实验数据量三万点设备是普通办公笔记本。纯Entity直接渲染初始化耗时约4秒相机拖拽时帧率最低掉到18fpsCPU占用经常飙到90%以上。开启EntityCluster聚合后初始加载降到了2秒左右正常交互帧率稳定在35fps以上CPU占用降了一半。后来又单独用Primitive自研方案测试了十万点场景初始化耗时控制在1秒内交互帧率基本稳定在50fps以上。代价是开发量多出了将近两个工作日而且聚合粒度的交互表现需要额外调优。综合来看两三万点以下用官方聚合方案完全足够超过十万点时再考虑走上层路线。中间的量级可以尝试混合方案Entity聚合用于展示Primitive用于后台计算热点密度。5. 常见问题排查速查表POI点聚合看着简单实际落地时坑不少。我把这几年遇到的高频问题整理成了一张表方便兄弟们排查问题现象可能原因处理方案聚合点显示为默认蓝色样式设置不生效clusterEvent里修改的是聚合Entity但聚合样式被scene.clusterBillboard覆盖直接修改scene.clusterBillboard和scene.clusterLabel的样式点击聚合点没有响应聚合实体可能不是通过id拾取拾取结果里id为空检查pick返回对象改用picked.primitive处理或确认聚合Entity已挂properties聚合后普通POI的billboard图标消失聚合生效时被聚合的Entity隐藏是正常行为不要尝试在聚合事件里强制显示原Entity否则会导致渲染混乱相机拉低后聚合散开很慢或闪跳数据量过大或聚合回调里做了耗时操作精简clusterEvent逻辑必要时用requestAnimationFrame做节流pixelRange值一样但不同区域聚合效果差异很大不同区域POI密度差异大单一参数难免顾此失彼按需要把聚合参数做成动态的或者按网格区域差异化配置聚合点数量显示为0或不刷新聚合Entity的label文本更新时机不对确保在clusterEvent里对_cluster.label.text赋值而非创建时设置一次地图居中后聚合错位相机变换时聚合位置未更新检查是否在相机移动结束后调用了dataSource.clustering.update()或升级Cesium版本其中点击聚合点没反应是最多人踩的坑。实际上是很多新手把聚合Entity当成普通Entity去看待直接在click监听里用picked.id.name取数据结果发现什么都没有。聚合Entity默认没有name它的信息主要靠你手动在clusterEvent里挂载这一步容易漏。还有一个细节容易忽略viewer.scene.pick在聚合点上的返回结果里picked.id有时可能不是Entity而是一个内部对象。稳妥的做法是在pick后先判断picked.id instanceof Cesium.Entity再做后续处理。6. 写在最后我这两年的一线体会Cesium的POI点聚合表面上是几个参数开关的事真正铺开做的时候才会发现里面的门道不少。我给新人的建议是第一步先把官方EntityCluster跑通理解pixelRange和minimumClusterSize的含义第二步再用clusterEvent去自定义样式和交互最后才考虑性能边界优化数据加载和渲染管线。这个顺序能让你少走很多弯路。我之前吃过一次亏项目上线前测试时把pixelRange调成了5结果POI密度稍高的区域几乎看不出聚合效果用户反馈地图上全是图标又卡又乱。后来反思了一下聚合参数一定要结合真实业务数据来做验证不能拍脑袋定值。还有个一直在用的小技巧把聚合参数开放成调试面板里的可调项部署到测试环境后让产品经理自己拖滑块调调到满意了再把数值固化进配置里。这样既能快速收敛参数也让团队里每个人对聚合效果有了直观认识。如果刚接触Cesium建议直接从最新的稳定版开始老版本里一些聚合相关的bug在新版中修了不少。文档方面Cesium官方示例的Clustering就是很好的学习起点把示例代码跑通之后再叠加自己的业务逻辑比对着网上零散代码抄要靠谱得多。本文还有配套的精品资源点击获取