1. 项目概述：为什么我们需要动态水面？
在三维地理信息可视化领域，水面效果的真实感直接决定了场景的沉浸感。无论是模拟洪水淹没分析、构建数字孪生城市的水系，还是开发游戏中的湖泊海洋，一个能随视角、时间或数据变化的动态水面，都是提升视觉效果的关键。Cesium作为领先的Web三维地球引擎，其原生提供了Water材质，但它通常用于覆盖整个地球或特定矩形区域，对于现实中不规则的湖泊、池塘、水库等任意多边形水域，就显得力不从心了。
这就是“Cesium动态水面（任意多边形PolygonGeometry）”要解决的核心痛点。我们需要的不是一张铺满全球的“水毯”，而是一块能够严丝合缝贴合在复杂岸线边界内，并且拥有波动、反射、折射等动态效果的“定制水片”。这个需求听起来简单，但实操起来，从几何体构建、材质配置到性能优化，每一步都有不少门道。我接手过不少相关项目，从简单的静态水域到需要实时响应水位数据变化的动态水面，踩过不少坑，也总结了一套稳定高效的实现方案。今天，我就把这个从零到一的保姆级流程拆开揉碎了讲给你听，无论你是刚接触Cesium的新手，还是想优化现有水面效果的老手，都能找到可以直接“抄作业”的代码和思路。
2. 核心思路与方案选型：不止一种“造水”法
在动手写代码之前，我们先理清思路。在Cesium中为一个任意多边形区域创建动态水面，本质上需要解决两个问题：“形状”和“质感”。
2.1 形状问题：如何定义水域边界？
Cesium的几何图形体系里，RectangleGeometry是矩形，CircleGeometry是圆形，而我们的不规则多边形，自然要用PolygonGeometry。这是最直接、最符合语义的选择。PolygonGeometry允许我们传入一组经纬度坐标点（Cartesian3数组）来定义多边形的轮廓。但这里有个关键点：PolygonGeometry生成的是一个“体”（如果指定了高度）或一个“面”。而水面通常被建模为一个无限薄的、带有特定材质的表面。因此，我们的核心工作是创建一个PolygonGeometry实例，然后为其赋予一个能模拟水动态效果的材质。
2.2 质感问题：如何模拟水的动态效果？
Cesium提供了几种实现动态视觉效果的方式：
- 原生
Water材质 +RectangleGeometry：最简单，但只适用于矩形区域，不符合我们的“任意多边形”要求。 - 自定义
Material材质：这是实现我们目标的核心路径。我们可以编写GLSL着色器代码，或者利用Cesium内置的材质模板（如Water、ElevationContour等），将其应用在PolygonGeometry上。自定义材质能完全控制水面的颜色、波纹频率、法线贴图、反射折射计算等所有视觉属性。 - 使用
GroundPrimitive：这是性能更优的选择。GroundPrimitive是Cesium中用于在地形表面绘制几何图形的特殊图元，它能够与地形进行深度测试并自动贴合地形起伏。对于需要与复杂地形（如山谷中的河流）完美结合的水面，GroundPrimitive搭配自定义材质是首选方案。它避免了Primitive可能出现的Z-fighting（深度冲突）问题。 - 使用
Primitive：更基础的图元，适用于平面或特定高度上的水面。如果水域区域地形平坦，或你希望水面保持一个绝对高度（如海平面），使用Primitive也是可行的，且控制更直接。
2.3 最终方案决策
综合考量形状的任意性、效果的动态性以及与地形的交互，我推荐的最佳实践方案是：使用GroundPrimitive承载一个基于PolygonGeometry构建的几何体，并为该几何体应用一个经过调整的自定义Water材质。
这个方案的优势在于：
- 形状贴合：
PolygonGeometry完美定义任意边界。 - 地形适配：
GroundPrimitive确保水面与地形无缝衔接，不会悬空或穿透。 - 效果真实：自定义
Water材质提供了波纹、镜面反射、基础颜色等动态属性。 - 性能可控：
GroundPrimitive针对地表渲染优化，比大量使用Entity（如PolygonGraphics）性能更好。
接下来，我们就按照这个方案，一步步实现它。
3. 环境准备与基础几何体创建
在开始编写核心的水面效果之前，我们需要搭建好基础场景并创建出多边形的几何体。这是所有后续工作的基石。
3.1 初始化Cesium Viewer
首先，确保你有一个可以运行的Cesium开发环境。这里我们直接通过CDN引入，创建一个基础的HTML文件。
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Cesium动态多边形水面</title> <script src="https://cesium.com/downloads/cesiumjs/releases/1.107/Build/Cesium/Cesium.js"></script> <link href="https://cesium.com/downloads/cesiumjs/releases/1.107/Build/Cesium/Widgets/widgets.css" rel="stylesheet"> <style> html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; padding: 0; overflow: hidden; } </style> </head> <body> <div id="cesiumContainer"></div> <script> // 你的Cesium代码将在这里编写 Cesium.Ion.defaultAccessToken = '你的Ion访问令牌'; // 请替换为你的有效Token const viewer = new Cesium.Viewer('cesiumContainer', { terrainProvider: Cesium.createWorldTerrain(), // 使用世界地形，这对水面贴合很重要 baseLayerPicker: false, geocoder: false }); // 将视角定位到一个有湖泊的区域，例如中国的洞庭湖附近 viewer.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(112.8, 29.3, 800000), orientation: { heading: 0, pitch: -60, // 俯视角度，便于观察水面 roll: 0 } }); </script> </body> </html>注意：务必申请并替换
Cesium.Ion.defaultAccessToken为你自己的令牌。没有地形数据，GroundPrimitive的效果会大打折扣。
3.2 定义任意多边形坐标
我们以模拟一个简单的不规则湖泊为例。你需要准备一组经纬度坐标，这些坐标按顺序连接起来构成多边形的边界。这里我手动定义了一个四边形的坐标，实际项目中这些数据可能来自GeoJSON、KML文件或后端API。
// 在viewer初始化代码之后继续编写 // 定义多边形顶点坐标（以洞庭湖大致轮廓为例，这里简化为四边形） const polygonPositions = Cesium.Cartesian3.fromDegreesArray([ 112.5, 29.5, // 点1 113.2, 29.5, // 点2 113.1, 28.9, // 点3 112.6, 28.8 // 点4 // 注意：第一个点和最后一个点不需要重复，Cesium会自动闭合多边形。 ]); // 为了可视化这个多边形范围，我们可以先用一个Entity轮廓线标出来 const outlineEntity = viewer.entities.add({ polygon: { hierarchy: new Cesium.PolygonHierarchy(polygonPositions), material: Cesium.Color.TRANSPARENT, outline: true, outlineColor: Cesium.Color.RED, outlineWidth: 3, height: 0, // 暂时放在0高度 extrudedHeight: 0 } });运行代码，你应该能看到一个红色的多边形轮廓线出现在地球上。这确认了我们的坐标定义是正确的。
3.3 创建PolygonGeometry实例
Entity的PolygonGraphics易于使用，但为了将其转换为GroundPrimitive所需的几何体，我们需要先创建底层的PolygonGeometry。
// 创建多边形几何体 const polygonGeometry = new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy(polygonPositions), vertexFormat: Cesium.VertexFormat.POSITION_AND_NORMAL, // 必须包含法线，用于光照和材质计算 height: 0, // 几何体基准高度。对于GroundPrimitive，这个高度是相对于椭球面的。 extrudedHeight: undefined, // 我们不创建立体拉伸体 stRotation: 0, // 纹理旋转，暂时为0 });这里的关键参数是vertexFormat。Cesium.VertexFormat.POSITION_AND_NORMAL告诉几何体需要计算并包含顶点法线信息。法线对于后续材质（尤其是Water这种依赖光照和法线贴图的材质）的正确渲染至关重要。如果只包含POSITION，水面可能会失去立体感，看起来像一张平坦的贴纸。
4. 核心环节：自定义Water材质与GroundPrimitive构建
这是实现动态水面效果最核心的一步。我们将深入Cesium的材质系统，创建一个适配我们多边形几何体的动态水面。
4.1 理解Cesium的Water材质
Cesium的Water材质是一个内置的复杂材质，它通过着色器（Shader）混合了多种效果：
- 法线贴图扰动：模拟水面的波纹细节。通常使用一张或多个法线贴图（Normal Map）并让它们随时间滚动，产生动态波纹。
- 镜面反射：计算对天空盒（SkyBox）或场景中其他物体的反射。
- 菲涅尔效应（Fresnel Effect）：模拟视线与水面夹角不同时反射和折射强度的变化（视线越平，反射越强）。
- 基础色与混浊度：定义水的颜色和透明度。
我们可以直接使用Cesium.Material.WaterType，但为了获得更多控制权（比如调整波纹大小、速度、反射强度等），我们需要通过Cesium.Material.fromType()方法创建并配置它。
4.2 创建并配置自定义Water材质
// 创建自定义Water材质 const waterMaterial = Cesium.Material.fromType('Water', { // 基础颜色。RGBA格式，A分量控制透明度。这里设置为半透明的蓝绿色。 baseWaterColor: new Cesium.Color(0.1, 0.3, 0.6, 0.8), // 波纹（凹凸）贴图。Cesium内置了一张不错的法线贴图。 normalMap: './assets/waterNormals.jpg', // 你可以替换为自己的法线贴图 // 注意：如果使用本地图片，需要确保路径正确或将其放到你的服务器上。 // 也可以使用Cesium内置的URL，但需要网络访问。 // frequency: 控制波纹的密度/频率。值越大，波纹越细密。 frequency: 100.0, // animationSpeed: 控制波纹动画的速度。值越大，流动越快。 animationSpeed: 0.05, // amplitude: 控制波纹的振幅（高度）。值越大，波浪感越强。 amplitude: 5.0, // specularIntensity: 镜面反射强度。值越大，高光越亮。 specularIntensity: 0.5, // 菲涅尔效应相关的偏移量和乘数，用于精细控制反射/折射比例。 fresnelOffset: 0.3, fresnelMultiplier: 5.0, });实操心得：
normalMap的选取至关重要。Cesium示例中常使用一张名为waterNormals.jpg的平铺法线贴图。你可以自己制作或从网上下载类似的无缝平铺水波纹法线贴图。将其放入你的项目assets目录并更新路径。如果暂时没有，可以先注释掉normalMap配置，材质会使用一个简单的替代算法，但效果会大打折扣。
4.3 将几何体与材质结合为GroundPrimitive
现在，我们有了几何体（polygonGeometry）和材质（waterMaterial），需要用GroundPrimitive将它们组装起来并添加到场景中。
// 创建GroundPrimitive const waterPrimitive = new Cesium.GroundPrimitive({ geometryInstances: new Cesium.GeometryInstance({ geometry: polygonGeometry, id: 'myDynamicWaterPolygon', // 给一个ID，便于后续查找或操作 attributes: { // 这里可以添加一些实例属性，但非必须 } }), appearance: new Cesium.MaterialAppearance({ material: waterMaterial, // MaterialAppearance的渲染状态配置 translucent: true, // 材质是半透明的，必须设为true closed: true, // 多边形是闭合的 faceForward: true, // 确保正反面渲染正确 }), // GroundPrimitive的特定配置 releaseGeometryInstances: false, // 建议设为false，保留几何体实例引用 allowPicking: false, // 是否允许鼠标拾取，根据需求设置 asynchronous: true, // 异步创建，避免阻塞主线程 }); // 将水面图元添加到场景的PrimitiveCollection中 viewer.scene.primitives.add(waterPrimitive); // 为了对比，可以隐藏之前用于示意的红色轮廓线 outlineEntity.show = false;刷新页面，你应该能看到之前红色轮廓线内，出现了一片具有动态波纹效果的蓝色水面。它应该很好地贴合了地形（如果你使用了createWorldTerrain）。
4.4 关键参数详解与调优建议
baseWaterColor：这不是水的最终颜色。在Water材质中，它会与反射的天空颜色、深度效果等混合。通常设置为一个较深的颜色（如深蓝、深绿），透明度（A）在0.7-0.9之间能获得较好的半透效果。frequency与amplitude：这是一对需要平衡的参数。frequency控制波纹的“数量”，amplitude控制波纹的“高度”。想象一下真实的水面：开阔湖面（低频、低振幅） vs 湍急小溪（高频、高振幅）。对于大湖，建议frequency在50-150，amplitude在1.0-10.0之间调试。animationSpeed：控制波纹流动速度。值太小（如0.001）水面会显得呆滞，值太大（如0.1）又会显得不自然。0.01到0.05是一个比较自然的范围。specularIntensity：模拟阳光在水面的高光。晴天可以调高（0.5-0.8），阴天可以调低（0.1-0.3）。translucent: true：这个非常重要！如果你的水面材质设置了透明度（baseWaterColor的A < 1.0），或者材质本身是半透明的，那么MaterialAppearance中的translucent必须设置为true，否则透明度将不会生效，水面会变成不透明的色块。
5. 高级技巧与性能优化
实现基础效果只是第一步。要让你的动态水面在复杂项目中稳定、高效、美观地运行，还需要掌握以下高级技巧。
5.1 处理复杂多边形（带孔洞）
现实中的水域常有岛屿（即多边形中的孔洞）。PolygonGeometry天然支持带孔洞的多边形定义。你需要使用PolygonHierarchy的holes属性。
// 假设outerRing是外圈多边形坐标 const outerRing = Cesium.Cartesian3.fromDegreesArray([...]); // 假设holeRing是内圈（孔洞）多边形坐标，顶点顺序应与外圈相反（通常是顺时针 vs 逆时针） const holeRing = Cesium.Cartesian3.fromDegreesArray([...]); const polygonGeometryWithHole = new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy(outerRing, [new Cesium.PolygonHierarchy(holeRing)]), vertexFormat: Cesium.VertexFormat.POSITION_AND_NORMAL, height: 0, }); // 后续创建GroundPrimitive的步骤完全相同5.2 水面高度控制与地形贴合
在上面的例子中，我们将几何体的height设为0。这意味着水面几何体创建在WGS84椭球体的表面（海拔0米）。当开启地形后，GroundPrimitive会自动将其“贴”到地形上。但有时我们需要水面位于一个特定的海拔高度（例如，模拟海拔500米的水库）。
const desiredAltitude = 500; // 单位：米 // 方法：将多边形每个顶点的高度设置为目标海拔 const positionsWithHeight = []; for (let i = 0; i < polygonPositions.length; i++) { const cartographic = Cesium.Cartographic.fromCartesian(polygonPositions[i]); cartographic.height = desiredAltitude; positionsWithHeight.push(Cesium.Cartographic.toCartesian(cartographic)); } const polygonGeometryAtHeight = new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy(positionsWithHeight), vertexFormat: Cesium.VertexFormat.POSITION_AND_NORMAL, // 注意：这里不再设置height属性，因为顶点坐标已经包含了高度信息。 // 如果设置了height，它会被加到顶点坐标的高度上。 });注意事项：使用
GroundPrimitive时，如果顶点本身有高度且地形也有起伏，Cesium会尝试将几何体“压”到地形上。如果你希望水面严格保持一个平面高度而忽略地形（即“悬空”或“填充”），可能需要考虑使用Primitive而非GroundPrimitive，或者对地形进行预处理（如挖坑）。
5.3 性能优化：几何体简化与实例化
- 几何体简化：如果你的多边形边界非常复杂（例如有成百上千个顶点），这会对渲染性能造成压力。可以考虑在服务端或前端使用道格拉斯-普克算法等简化算法，在保持形状大致不变的前提下减少顶点数量。Cesium本身不提供此功能，需要引入第三方库（如
turf.js的simplify方法）或自行实现。 - 实例化渲染：如果你需要在场景中创建大量形状相同但位置不同的水面（例如，多个相同的池塘），可以使用
GeometryInstance的modelMatrix属性。通过一个几何体定义，配合多个不同的变换矩阵（modelMatrix）来创建多个实例，GPU可以一次性渲染它们，极大提升性能。
const baseGeometry = ... // 创建你的基础多边形几何体 const baseMaterial = ... // 创建你的水面材质 const instances = []; for (let i = 0; i < 10; i++) { // 为每个实例计算一个偏移位置（例如，沿经度方向排列） const translation = Cesium.Cartesian3.fromDegrees(112.8 + i * 0.1, 29.3, 0); const modelMatrix = Cesium.Matrix4.fromTranslation(translation); instances.push(new Cesium.GeometryInstance({ geometry: baseGeometry, id: `waterInstance_${i}`, modelMatrix: modelMatrix // 应用变换矩阵 })); } const batchPrimitive = new Cesium.GroundPrimitive({ geometryInstances: instances, // 传入实例数组 appearance: new Cesium.MaterialAppearance({ material: baseMaterial, translucent: true, }), // ... 其他配置 }); viewer.scene.primitives.add(batchPrimitive);5.4 动态效果增强：让水面“活”起来
基础的Water材质已经提供了动画。但我们还可以做得更多：
- 随时间变化的水位：通过定期更新几何体顶点的高度并重新创建
GroundPrimitive，可以模拟水位上涨或下降。注意：频繁重建几何体开销较大，对于平滑动画，可以考虑使用着色器在顶点着色器中动态调整高度，但这属于高级GLSL编程范畴。 - 与天气系统联动：根据场景中的天气（晴天、雨天、风暴），动态调整材质的
specularIntensity（晴天调高）、baseWaterColor（雨天调灰）、amplitude（风暴天调高）等参数。 - 添加焦散效果：更高级的效果，模拟水底的光斑。这通常需要额外的渲染通道或更复杂的着色器代码，超出了本教程基础范围，但你可以搜索“Cesium caustics water”找到相关社区方案。
6. 常见问题与排查技巧实录
在实际开发中，你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了速查表。
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 水面完全不显示 | 1. 访问令牌无效或未设置。 2. 地形未加载， GroundPrimitive依赖地形。3. 几何体坐标定义错误（如顺序不对、点数太少）。 4. 材质创建失败（如图片路径错误）。 | 1. 检查浏览器控制台（F12）是否有Cesium Ion认证错误。 2. 确保 viewer使用Cesium.createWorldTerrain()，并等待地形加载完成（监听viewer.terrainProvider.readyPromise）。3. 先用 Entity显示一个红色轮廓线，确认多边形位置正确。4. 检查控制台是否有“Failed to load image”错误，尝试注释掉 normalMap配置看是否显示。 |
| 水面显示为不透明的纯色块 | MaterialAppearance的translucent属性未设置为true。 | 在创建MaterialAppearance时，确保translucent: true。这是新手最常见的错误之一。 |
| 水面边缘有锯齿或闪烁（Z-fighting） | 水面几何体与地形表面过于接近，深度缓冲精度不足导致渲染顺序冲突。 | 1.最佳方案：使用GroundPrimitive，它专为地表渲染设计，能更好地处理深度冲突。2. 如果仍用 Primitive，可以尝试将水面几何体的height略微提高（如0.1米）。3. 在 Material中启用polygonOffset（如果支持）。 |
| 水面波纹不动或动画很卡顿 | 1.animationSpeed设置为0或太小。2. 浏览器性能不足，可能是多边形顶点太多或场景中其他元素过载。 | 1. 逐步增加animationSpeed值（如从0.01开始）。2. 打开浏览器的性能监视器，检查帧率（FPS）。简化多边形几何体，或减少场景中其他复杂模型的数量。 |
| 水面反射天空盒的内容很奇怪或过曝 | Water材质的反射计算依赖于场景的skyBox和sun。如果场景光照设置异常，会导致反射错误。 | 1. 检查viewer.scene.skyBox和viewer.scene.sun是否启用且正常。2. 调整 Water材质的specularIntensity和fresnel参数，降低反射强度。 |
| 在特定视角或缩放级别水面消失 | 可能是视锥体裁剪（Frustum Culling）导致。几何体相对于相机太远或不在视野内时被剔除。 | GroundPrimitive的裁剪比较智能。如果问题持续，可以尝试：1. 检查多边形坐标是否在可视范围内。 2. 对于非常大的水面，确保其边界计算正确。通常不需要手动干预。 |
控制台报错：Vertex format requires normals... | 创建PolygonGeometry时，vertexFormat未包含Cesium.VertexFormat.POSITION_AND_NORMAL。 | 在实例化PolygonGeometry时，显式指定vertexFormat: Cesium.VertexFormat.POSITION_AND_NORMAL。 |
独家避坑技巧：
- 调试利器：Cesium Inspector：在浏览器控制台输入
viewer.extend(Cesium.viewerCesiumInspectorMixin);，可以激活Cesium Inspector工具。在“Primitives”选项卡下，你可以看到所有Primitive和GroundPrimitive，并可以切换显示/隐藏、查看其几何和材质信息，是排查渲染问题的神器。 - 分步验证法：当效果不达预期时，采用“剥洋葱”法。先注释掉材质，用
Cesium.Color.RED.withAlpha(0.5)这样的简单颜色材质测试几何体是否正确显示和定位。再逐步加上Water材质的各个属性，每次只改一个参数，观察变化。 - 法线贴图预处理：如果你使用自己的法线贴图，确保它是无缝平铺（Seamless Tiling）的，并且颜色空间正确（通常法线贴图是线性空间）。可以用Photoshop或在线工具处理。一张好的法线贴图能让水面质感提升几个档次。
最后，我个人在实际项目中的体会是，动态水面的效果“七分靠材质，三分靠调参”。没有一套参数能放之四海而皆准。对于城市内涝模拟，你可能需要高频、低振幅、颜色偏浑浊的水面；对于高原湖泊，则需要低频、高反射、颜色清澈的效果。最好的方法是，准备好真实水域的参考图片或视频，在Cesium中一边调整参数一边对比，直到获得最符合场景氛围的效果。这个过程虽然繁琐，但当你调出以假乱真的水面时，那种成就感是无与伦比的。