简介CesiumThreejs.zip 是一份面向 Web 三维开发者的整合示例聚焦 Cesium 地球模型与 Three.js 3D 渲染的协同工作适合需要在真实地理环境中展示复杂三维模型的开发者。通过将 Cesium 的高精度地形、卫星影像与 Three.js 灵活的模型渲染能力结合可以解决单独使用 Cesium 时对自定义模型表现力不足的问题。压缩包大小约 4.8MB文件总数与类型明细暂未公开可解压后直接查看示例代码。已有 444 人学习适用于具备一定 Cesium 基础、想引入 Three.js 丰富图形能力的开发者。内含可运行的整合工程围绕 Cesium 与 Three.js 的坐标系统转换、相机与视口同步、GLTF/OBJ 等格式模型加载、场景挂载与位姿更新等关键环节展开并给出地理坐标与 WebGL 坐标对齐的简明思路帮助读者在实践中快速掌握双引擎配合方式节省自行调试和试错的时间。1. 定位这个整合项目解决什么问题1.1 Cesium 与 Three.js 各自的边界接手这个CesiumThreejs.zip项目之前我一直在思考一个问题为什么不能只用一个三维引擎把 GIS 和特效全干完实际用了几年之后结论其实很清楚——Cesium 的地球、地形、影像、3D Tiles 能力无可替代但你让它去做高动态的粒子、复杂的自定义着色器、精细的构件级模型表达它写起来确实别扭Three.js 反之自由度和生态极强但你要它管理全球坐标系、切片加载、地形调度那基本等于重新造一个 GIS 引擎。所以项目里最核心的判断是Cesium 负责“地球空间底座”Three.js 负责“场景特效增强”。两者通过 WebGL 上下文共享在同一个 Canvas 上叠加渲染互相不抢资源、不出现双窗口切换的割裂感。这也是CesiumThreejs.zip被反复讨论的原因——它不是一个库而是一整套整合方案把雷达扫描、动态光照、可视域分析、天际线这类在 Cesium 里做起来费劲的效果全部转移到 Three.js 侧实现。1.2 为什么要共享 GL 上下文先说说为什么不直接用两个独立的 Canvas 或两个独立 WebGL 实例。你如果尝试过在同一个页面里同时 new 一个 Cesium.Viewer 和一个 THREE.WebGLRenderer大概率会遇到页面黑屏、GPU 资源冲突、浏览器崩溃或者帧率直接掉到 20 FPS 以下。原因在于浏览器对 WebGL 上下文的数量和 GPU 内存分配是有限制的两个上下文同时存在意味着两套渲染管线、两套状态机、两套纹理缓冲机器稍微差一点就受不了。共享 GL 上下文的思路是让 Cesium 创建唯一一个 WebGL 上下文Three.js 拿到这个上下文去初始化自己的 renderer也就是context复用。这样两个引擎共用同一个 Canvas、同一条 GPU 管线一个是另一个的超集渲染顺序可控、资源开销也小得多。项目里大量效果的实现都依赖这个前提所以我会把这部分放在第二节单独讲。1.3 zip 包内容与整体架构拿到这个 zip 包建议先别急着跑先把目录结构扫一遍。一般会发现这样几个核心模块src/core初始化 Cesium Viewer、创建共享 GL 上下文、Three.js Renderer 挂载src/effects雷达、动态光照、水面、可视域、天际线等自定义效果src/cameraCesium 相机和 Three.js 相机同步逻辑src/utils坐标转换、矩阵工具、shader 公共库。这种分层的好处是效果模块只依赖 core 提供的共享上下文不直接操作 Cesium 内部替换某个效果时不会伤到地基。项目的整体架构可以用一句话概括Cesium 负责出图Three.js 负责在这张图上“画特效”中间层只做两件事——上下文共享和相机同步。下面我从工程搭建一步步展开。2. 工程搭建与版本选型2.1 版本组合实测先给出一组我实测下来最稳的版本组合省得你在版本海洋里踩坑依赖推荐版本说明Cesium1.108这个版本起对 WebGL2 的支持比较好动态光照和自定义着色器不容易出奇奇怪怪的问题Three.jsr160 ~ r185r185 有一定坑下面单独讲r160 以上对共享上下文兼容性较好vue3.x / 2.7用纯 HTML 也行原理一致推荐 Vue3 Vite 做工程化vite4.x / 5.x开发调试方便Cesium 的 CESIUM_BASE_URL 配置网上有很多资料为什么要强调版本因为 Cesium 在不同版本里对viewer.scene.context的暴露方式有差异。早期版本还能直接拿_cesiumWidget._context后期版本要绕一层Three.js 在 r150 之后对 WebGLRenderer 的context参数也做了调整旧写法在新版本里会直接报错。这个 zip 包里如果锁定了版本建议保持锁定如果你是自己从头搭认准上面的组合能少走几天弯路。2.2 初始化顺序不能乱共享上下文最忌讳的就是初始化顺序错乱。我犯过的错误是先把 Three.js renderer 创建出来再去创建 Cesium viewer结果 Cesium 直接报 WebGL 上下文类型不匹配。正确顺序是创建 Cesium Viewer从 Cesium 的渲染器里获取 WebGL 上下文使用该上下文创建 THREE.WebGLRenderer在 Cesium 每一帧渲染完成后调用 Three.js 的 render 方法叠加绘制。顺序一乱WebGL 状态的绑定就会出现不可预期的问题轻则特效不显示重则整个地球都不渲染。代码层面大概是这样const viewer new Cesium.Viewer(cesiumContainer, { contextOptions: { webgl: { alpha: true, antialias: true, preserveDrawingBuffer: true } } }); const gl viewer.scene.context._gl; threeRenderer new THREE.WebGLRenderer({ canvas: viewer.canvas, context: gl, antialias: true }); threeRenderer.setSize(window.innerWidth, window.innerHeight); threeRenderer.autoClear false;注意autoClear false很关键。如果不设置Three.js 每帧都会清掉 Cesium 已经画好的颜色缓冲地球就会闪成一片黑。2.3 共享上下文的关键参数共享上下文的坑多半出在创建上下文时的参数上。我的建议是保留alpha: true这样 Three.js 侧绘制透明背景时能跟 Cesium 的底图自然叠加preserveDrawingBuffer: true一定要开否则截图、后期合成时会拿到空白画布别问我是怎么知道的。contextOptions: { webgl: { alpha: true, antialias: true, depth: true, stencil: false, preserveDrawingBuffer: true, powerPreference: high-performance } }powerPreference: high-performance也是刚需默认的 default 在某些浏览器上会切到低功耗 GPU后面跑粒子特效的时候帧率直接崩。3. 相机同步与坐标转换3.1 坐标转换从经纬度到 Three.js 世界只要涉及 Cesium 和 Three.js 联动就躲不开坐标转换。Cesium 常用的是 WGS84 经纬度和 Cartesian3 直角坐标Three.js 用的是以原点为中心的三维笛卡尔坐标系。直接拿经纬建场景你会发现模型飞到了莫名其妙的位置。思路是这样的先在 Cesium 里选定一个中心点比如经纬度 (113.9, 22.5)然后用Cesium.Transforms.eastNorthUpToFixedFrame生成一个局部坐标系把这个局部坐标系的旋转和平移提取出来作为 Three.js 场景中物体的基准变换。const center Cesium.Cartesian3.fromDegrees(113.9, 22.5); const localToWorld Cesium.Transforms.eastNorthUpToFixedFrame(center); const matrix4 new THREE.Matrix4().fromArray( Cesium.Matrix4.toArray(localToWorld) );一句话解释这个转换的意义把基于地心的大坐标搬到中心点附近的小坐标系里。这样 Three.js 里的模型坐标就在 0 附近浮动了浮点精度不会崩各种计算的数值稳定性也好很多。3.2 相机同步每一步都要对齐相机同步是共享上下文里最容易出问题的环节。Cesium 的相机是一个带位置、方向、上方向的摄像机模型Three.js 的 PerspectiveCamera 也是类似结构但两者对朝向矩阵的定义有细微差异。项目里我用的方案是每帧从 Cesium 相机读取positionWC、directionWC、upWC转换成 Three.js 相机的位置和视图朝向。function syncCamera() { const cam viewer.camera; threeCamera.position.copy(toLocalVec(cam.positionWC)); threeCamera.up.copy(toLocalVec(cam.upWC)); threeCamera.lookAt(toLocalVec(cam.positionWC.add(cam.directionWC))); threeCamera.updateProjectionMatrix(); }这里toLocalVec需要把世界坐标准换到局部坐标我一般用一个临时向量池const scratch new THREE.Vector3(); function toLocalVec(cartesian3) { scratch.set(cartesian3.x, cartesian3.y, cartesian3.z); return scratch.applyMatrix4(invLocalMatrix); }还有一个细节Cesium 相机的 aspect 是自动算的但 Three.js 相机的 aspect 必须手动更新否则窗口缩放后透视关系会错位。建议在窗口 resize 的 listener 里同时更新 Cesium 和 Three.js 的 aspect。4. 落地效果雷达扫描、动态光照、可视域与天际线4.1 经典雷达扫描效果雷达扫描是很多 GIS 项目里常见的需求Cesium 社区有人用 Polygon 或 Material 做但效果往往不够灵活。用 Three.js 做雷达扫描思路是创建一个圆形平面给它的片元着色器传入扫过的角度和时间让扫描线以中心为轴旋转扫描区域呈现渐变光晕。关键 shader 逻辑我贴一下float angle atan(position.x, position.z); float sweep smoothstep(0.0, 0.3, fract(uTime * uSpeed - angle / 6.28318530718)); color mix(vec3(uColor), vec3(0.0), step(0.98, sweep)); opacity sweep * 0.6;注意角度计算要用atan而不是acos不然方向会错。生成平面时设置rotation.x -Math.PI / 2让它贴地或者根据模型需要稍微倾斜。雷达效果在项目里通常放在 Three.js 侧因为它的绘制频率很高用 Cesium 的 Primitive 绘制会更吃力稍不留神就吃满 CPU。4.2 动态光照与高逼真水面Cesium 版本迭代后自带的日光照效果已经不错但如果你要在局部场景做动态光柱、扫光、探照灯这类效果Cesium 的 API 显得很笨重。Three.js 里一个THREE.DirectionalLight或者自写一个光源体积就能解决问题。动态水面方面项目里可以直接在 Three.js 侧用平面几何体叠加法线贴图动画实现。比 Cesium 的 Material 方案更细腻因为你可以控制波纹的频次、方向以及反射强度。实现步骤大致是在 Cesium 中确定水面区域的经纬度范围计算出平面几何体的位置和尺寸在 Three.js 中创建 PlaneGeometry叠加法线扰动和菲涅尔反射 shader每帧更新纹理偏移让水面有流动感让水面几何体贴附到 Cesium 的地形高度上。这里要注意如果水面范围很大平面几何体建议分段否则顶点数量太少波纹细节不够但也不能太密否则 GPU 压力大一般 256x256 的段数对中线区域已经很好。4.3 可视域分析与天际线可视域分析和天际线分析是 GIS 里两个高频需求也是 Cesium 原生实现起来比较绕的场景。可视域分析的核心是“从某点看出去哪些区域可见、哪些不可见”传统做法是视线采样求交Cesium 自带的分析工具精度有余效率不足尤其在地形较大的场景会卡顿。在整合方案里可以用 Three.js 的射线检测来做快速可视域从观察点向四周发射一组射线射线与地形 Mesh 求交得到可见点集合再用线条或半透明面把这些点连起来。因为 Three.js 和 Cesium 能共享深度缓冲射线检测可以复用已经加载的地形数据性能比 Cesium 原生计算高不少。天际线分析的核心是提取场景中物体轮廓线。可以先用 Cesium 生成地表建筑模型的 Mesh然后用 Three.js 的后处理轮廓描边比在 Cesium 里用 Stencil 做更方便。如果你用到的是 3D Tiles 建筑数据还可以先筛选高度大于阈值的建筑再提取轮廓避免天际线被低矮建筑刷屏。4.4 模型节点与姿态控制项目里另一个高频需求是控制三维模型的姿态比如把 BIM 模型、机械设备模型按真实朝向摆放。Cesium 有ModelInstance和节点控制能力但当你需要逐节点修改、做序列帧动画、或者在模型上叠加特效标签时Three.js 的工具链更成熟。整合方案里通常这样操作把模型加载到 Three.js 场景 (GLTFLoader)用 Cesium 提供的局部 ENU 坐标系作为模型挂载点每帧从模型节点读取 world matrix再同步到 Cesium 中对应的 entity 上如果需要在 Cesium 拾取。这样既保留了 Cesium 对地球和底图的渲染又获得了 Three.js 对模型的精细控制能力。当然也有代价拾取和交互需要自己写比如射线拾取模型节点后用 Three.js 的Object3D名称做映射。5. Three.js r185 锯齿问题排查实录5.1 现象与原因搜索热词里“threejs 185版本 锯齿问题”出现频率很高我这边实际也遇到过而且只出现在 r185 这个版本附近。现象是模型边缘出现明显锯齿即使antialias: true也无济于事尤其在共享 GL 上下文场景下更为严重。原因要从两个层面看。第一Three.js 从某一版本开始会主动检测 WebGL 2 并默认使用 WebGL 2 上下文。WebGL 2 的默认 MSAA 行为和 WebGL 1 不同如果你共享的上下文由 Cesium 创建Cesium 自己又是按自己的规则创建的两者对 MSAA 的处理可能不一致。第二r185 里THREE.WebGLRenderer在context已存在时antialias参数会失效——因为上下文已经创建出来了样本数量在创建那一刻就定了后面改参数没用。5.2 解决方案我实测有效的方案有三个优先级从高到低在 Cesium 创建上下文时就把 antialias 打开。因为共享上下文的方式下MSAA 由 Cesium 创建的上下文决定alpha: true和antialias: true都要写全后面 Three.js 设不设antialias其实都无所谓。用后期处理做抗锯齿。如果实在搞不定 MSAA可以用 Three.js 的EffectComposer加一层 FXAA 或 SMAA。FXAA 性能最好SMAA 画质更好在场景像素密度较高时两者差异不大。开启渲染器像素比。renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2))强制采样率提升锯齿会明显减少。缺点是 GPU 负载上升移动端慎用。另外提一句不要试图在同一份代码里既用 Cesium 又让 Three.js 单独创建第二个 WebGL 上下文然后再去同步画面。这种做法基本等于放弃了共享上下文的全部优势也大概率会触发浏览器的上下文限制和性能告警别走这条路。6. 高频问题排查与性能优化建议6.1 常见问题速查表问题现象可能原因解决办法Three.js 特效不显示autoClear未设 false 导致清屏threeRenderer.autoClear false模型位置漂移局部坐标与 Cesium 世界坐标未正确转换检查 ENU 矩阵和逆矩阵是否同步点击交互失效Cesium 和 Three.js 的拾取时机冲突在 postRender 后统一处理拾取或分开两层拾取后合并截图黑屏preserveDrawingBuffer没开上下文创建时设为 true帧率掉到 30FPS 以下特效每帧重建几何或纹理优先用着色器动画避免直接更新顶点数据抗锯齿无效共享上下文 MSAA 由创建方决定在 Cesium 上下文创建时开启 antialias6.2 性能优化建议整合两个引擎之后最容易踩的坑就是让 Three.js 把整棵 Cesium 地球再渲染一遍。正确的思路是Three.js 只管“覆盖在上面的那部分内容”底层的全球地形、影像、3D Tiles 全部交给 Cesium。这样你的绘制调用数量能控制在一个很低的水平。我给项目定了几条性能底线Three.js 侧物体数量控制在 500 个 draw call 以内能用实例化 (InstancedMesh) 就绝不散装特效纹理统一用 512x512 或 256x256避免大尺寸纹理在移动端爆显存每帧只更新必要的 uniform不要在动画循环里 new 任何对象雷达扫描、水波这类高频率特效建议用 shader 实现而非修改顶点数组。另外要注意 Cesium 的postRender事件和 Three.js 的requestAnimationFrame不能同时驱动渲染。我在项目里统一用 Cesium 的postRender作为主循环因为 Cesium 需要保持他自己的帧率控制Three.js 的渲染放在这个回调里执行相当于把两套渲染合并成了一条流水线。实际操作后还有一个体会开发阶段务必打开浏览器 GPU 任务管理器或者用 Chrome 的chrome://gpu看 WebGL 状态栏。如果发现 GPU 进程异常、或者 WebGL 状态不是 Hardware accelerated排查共享上下文的问题会事半功倍。最后再分享一个小技巧如果你在共享上下文的项目里写了新的 shader调试时先用一个独立的 Three.js 场景把 shader 单独跑通再搬进整合项目。因为两个引擎叠加后错误栈经常被吞掉直接定位会花很多时间单独调试能帮你快速判断是 shader 问题、矩阵问题还是上下文状态问题。这个小习惯帮我省下了大量调试时间你也可以试试。本文还有配套的精品资源点击获取