简介：面向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秒，相机拖拽时帧率最低掉到18fps，CPU占用经常飙到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就是很好的学习起点，把示例代码跑通之后，再叠加自己的业务逻辑，比对着网上零散代码抄要靠谱得多。
本文还有配套的精品资源，点击获取
 01 实现第一颗灯泡的点亮)
