企业官网建设流程全解析

上个月在做一个智慧园区数字孪生项目，场景里需要模拟一天中从黎明到夜晚的光照变化，云层和星空也要跟着动。默认的 Cesium 天空盒是一张静态的六面立方体贴图，客户第一次看到就问了句：“这个背景是不是贴图贴死了？” 从那以后，我开始花时间研究如何在 Cesium 里做出会旋转的动态天空盒。折腾了大概两周，试过改源码、试过序列帧、也踩过不少 Cesium 版本升级后带来的坑，最后总算整理出一套能落地的方案。

这篇内容适合正在做数字孪生、智慧城市、三维可视化项目的 Cesium 开发者。如果你只是想在默认地球上换个天空盒贴图，那不用看这篇；但如果你需要让太阳、云层、星空场景真正“动起来”，并且让模型阴影和天空光照方向保持一致，这篇会很有用。核心思路有两个：一是直接改造 Cesium 引擎内部的 SkyBox，给它增加旋转矩阵支持；二是不动引擎，用预渲染的序列帧动态切换天空盒贴图。两条路各有取舍，下面我会把原理、代码、坑和优化全部分享出来。

1. 为什么默认天空盒不够用，旋转方案又好在哪

1.1 默认天空盒的静态局限

Cesium 的Viewer在创建时会自动带一个默认天空盒，通常是一个星空背景，由六张贴图组成，对应立方体的六个面。它在三维空间里表现为一个无限远的包围盒，相机动、它不动，本质上就是根据相机视线方向去 CubeMap 里采样颜色。

默认天空盒的问题不在于贴图质量，而在于它是完全静态的。没有时间概念，没有云层流动，没有太阳从东到西的位置变化。对于传统 GIS 场景，这个静态星空可能无所谓；但一旦到数字孪生、影视预演、科研仿真这类对时空一致性要求高的场景，静止天空就会显得“假”。

有人可能想，那我直接把默认天空盒的三十张贴图在 PhotoShop 里处理一遍，加个太阳和云彩，不就行了吗？可以，但这只是换了张静态图。客户要求的是上午九点太阳在东边、下午四点太阳在西边，这个需求靠单张贴图根本满足不了。

1.2 旋转天空盒到底解决什么问题

旋转天空盒的核心逻辑很简单：让立方体贴图的采样方向随时间发生变化。你 0 点时正东方向是星空，到早上 6 点时，正东方向变成了日出贴图区域。视觉上看起来，整个天穹在缓慢转动，太阳和星星的位置都跟着移动。

这个方案最大的优点是轻量。它不需要额外加载成百上千张贴图，不需要后台服务，不需要复杂的流体模拟。你只需要准备一组标准六面天空盒贴图，再在渲染阶段对采样向量做一个数学变换，就能模拟出天空随时间变化的效果。配合场景内光源方向一起旋转，还能让太阳位置和实体阴影保持同步，这是不少“伪动态天空”方案最容易忽略的地方。

至于为什么不直接用 WebGL 的纹理旋转参数、为什么不直接旋转整个场景，我在第二章会讲清楚。先记住一点：Cesium 的天空盒渲染走的是 Shader 采样，修改采样向量是最干净、最可控的做法。

1.3 两条技术路线怎么选

根据项目约束，我整理了两条可落地的路线，先把对比结果放出来：

我个人的判断标准是：如果你能接受在项目里使用自编译的 Cesium，并且以后还会做光照、雾效、昼夜节律这类高性能需求定制，那一定要选方案A。改一次源码，之后很多效果都能在引擎层顺手做掉；如果你只是做一个三五天的原型验收，或者团队里禁止改引擎包，那方案B更稳，毕竟不动核心代码，风险小得多。

方案A看起来复杂，但操作路径很清晰，关键是找到 SkyBox 的 Shader 文件和 JS 文件，插入旋转矩阵后重新构建。下面两章先解决原理问题，再进入实战。

2. SkyBox 渲染原理和旋转的数学基础

2.1 天空盒本质上是一个方向采样器

天空盒说穿了就是一个“方向到颜色”的查表过程。场景中的相机在一个非常大的立方体中心，这个立方体不会因为相机移动而移动，相机永远位于中心。渲染时，对每个像素，根据相机的视线方向去CubeMap纹理中取色，就得到了看似无限远的背景。

Cesium 内置的 SkyBox 也是这个思路。它用了一个单位立方体几何体，顶点位置直接作为纹理坐标，传入片段着色器后，用textureCube采样。由于立方体足够远，透视投影后所有方向都会覆盖屏幕，所以看起来就像整个天穹都贴上了纹理。

Cesium 原始的 SkyBox 着色器核心逻辑是这样的（不同版本写法略有差异）：

// SkyBoxVS.glsl attribute vec3 position; varying vec3 v_texCoord; void main() { v_texCoord = position; gl_Position = czm_viewProjection * czm_model * vec4(position, 1.0); }

// SkyBoxFS.glsl varying vec3 v_texCoord; uniform samplerCube u_cubeMap; void main() { vec4 color = textureCube(u_cubeMap, v_texCoord); gl_FragColor = color; }

注意片段着色器里采样的关键变量是v_texCoord。它代表的不是某个平面纹理坐标，而是空间中的方向向量。如果我们能让这个方向向量整体绕某个轴旋转一个角度，那么从相机里看到的结果就是“整个天穹在转”。

2.2 旋转矩阵怎么作用到采样向量上

要让天空盒绕 Y 轴旋转，最直接的办法是构造一个绕 Y 轴旋转的 3x3 矩阵，把采样方向向量乘上去。数学表达式很基础，绕 Y 轴旋转 θ 角度后的方向向量是：

x' = x * cosθ + z * sinθ y' = y z' = -x * sinθ + z * cosθ

在 Cesium 里，这对应Cesium.Matrix3.fromRotationY(angle, result)这个 API。它会生成一个符合 Cesium 右手坐标系的矩阵。

需要特别说明的是，Cesium 里绕 Y 轴到底往哪个方向偏，和你在 WebGL 里默认的旋转手势可能不完全一致。因为 Cesium 的地理坐标系、相机坐标系和普通三维建模软件的轴定义有差异，实际项目中如果你发现太阳是往反方向转，把角度取个负号，或者用Matrix3.transpose转置一下矩阵就好。这个不是智商问题，是坐标习惯问题。

片段着色器里加上旋转矩阵后，代码变成：

uniform mat3 u_rotation; void main() { vec3 dir = normalize(u_rotation * v_texCoord); vec4 color = textureCube(u_cubeMap, dir); gl_FragColor = color; }

由于textureCube对非归一化向量是会做内部处理的，但为了后续可能增加的边缘采样逻辑，还是建议先normalize一次。数学上，旋转矩阵不会改变向量长度，所以这一步不影响结果，但能让你在调试其他效果时少一些隐患。

2.3 为什么不能直接旋转 CubeMap 纹理本身

有新手朋友会问：能不能在 JavaScript 里给贴图对象设置一个旋转角度？很遗憾，WebGL 的 CubeMap 纹理就是六张 2D 纹理组合，纹理采样器只有 wrap、filter、mipmap 等参数，没有“旋转纹理”这个概念。你可以调整 Tiling 或 offset，但那主要面向 2D 纹理，不能对立方体贴图做整体旋转。

也有人想，那我不改 Shader，每帧生成一张新的六面贴图再传进去行不行？理论上行，但代价是每帧要重新上传六张图片到 GPU，显存带宽和 CPU 编码压力都很大。做一两次演示没问题，做成长期产品性能上吃不消。所以最优雅的方案仍然是改采样向量。

理解了这一步，方案A的所有技术门槛基本就消除了，剩下的就是找对文件、改对地方。

3. 实战方案A：改造 Cesium 引擎，给 SkyBox 增加旋转支持

3.1 改造前的环境与源码准备

如果你使用的是 Cesium 1.9x 及以上版本，源码目录结构是packages/engine/Source/...；如果用的是老版本，则直接把packages/engine去掉，路径变成Source/...。需要改的核心文件有三个：

• SkyBox.js：天空盒的 JS 逻辑，负责创建 DrawCommand、管理纹理对象。
• SkyBoxVS.glsl：顶点着色器，一般不用动。
• SkyBoxFS.glsl：片段着色器，旋转逻辑加在这里。

先准备一个能构建的 Cesium 工程。最简单的方式是克隆官方仓库，然后执行npm install。注意构建工具链需要 Node.js 环境，推荐使用 Node 16 或 18，太新或太旧都可能遇到和 Cesium 构建脚本不兼容的问题，这是个常识性坑。

在动手之前，建议先把源码对应文件打开看一遍，搜索u_cubeMap这个 uniform，你就能看到 SkyBox 的着色器是如何被引用的。不同 Cesium 版本里这段代码的位置可能有迁移，但命名通常不会变，搜索是很可靠的定位方式。

3.2 修改片段着色器，加旋转矩阵

找到SkyBoxFS.glsl，把它改成下面这样：

varying vec3 v_texCoord; uniform samplerCube u_cubeMap; uniform mat3 u_rotation; void main() { vec3 dir = normalize(u_rotation * v_texCoord); vec4 color = textureCube(u_cubeMap, dir); gl_FragColor = color; }

这里新增的u_rotation是个 3x3 矩阵。之所以用 3x3 而不是 4x4，是因为采样向量是方向向量，不是带位置的点向量，不需要平移，用 3x3 就够了。这一行改动不会显著增加 GPU 负载，矩阵乘法在片段着色器里几乎可以忽略不计。

如果你想在三维空间里同时绕 X、Y、Z 轴旋转，也可以在 CPU 端把三个轴的旋转矩阵相乘，得到一个复合矩阵后传进来。这个自己按需求扩展即可。

3.3 在 SkyBox.js 里创建并更新旋转矩阵

打开SkyBox.js，在构造函数末尾增加两个成员变量：

this._rotation = options.rotation || 0.0; this._rotationMatrix = Matrix3.clone(Matrix3.IDENTITY);

options.rotation是你希望天空盒初始绕 Y 轴旋转的角度值，单位是弧度。默认给 0，表示不旋转，和原来的行为保持一致。

然后在SkyBox.prototype.update方法里，创建 DrawCommand 之前加一段更新逻辑：

if (defined(this._rotation)) { Matrix3.fromRotationY(this._rotation, this._rotationMatrix); }

接下来找到创建 DrawCommand 时传入的uniformMap。SkyBox 内部本来就会绑定u_cubeMap，我们只需要再加入一个u_rotation：

uniformMap: { u_cubeMap: function() { return skyBox._cubeMap; }, u_rotation: function() { return skyBox._rotationMatrix; } }

这里要特别提醒一下：不同版本 Cesium 中uniformMap对象的字段名可能不是u_cubeMap，也可能是u_texture，你需要以实际源码为准。但整体思路是完全一样的，先找到原有 uniform，再往里追加一个矩阵 uniform。你可以在控制台打印 SkyBox 的命令对象来调试，也可以直接打开构建后的产物搜索SkyBoxFS字符串，再回推相应位置。

3.4 重新构建并接入项目

修改完源码后，执行 Cesium 的标准构建命令：

npm run build -- --release

构建完成后，会输出新的Cesium.js和Cesium.css，把项目里的 Cesium 依赖替换成这个自编译版本即可。

接入时只需要在创建 Viewer 后手动设置一次 skyBox：

const viewer = new Cesium.Viewer('cesiumContainer'); viewer.scene.skyBox = new Cesium.SkyBox({ sources: { positiveX: './skybox/px.jpg', negativeX: './skybox/nx.jpg', positiveY: './skybox/py.jpg', negativeY: './skybox/ny.jpg', positiveZ: './skybox/pz.jpg', negativeZ: './skybox/nz.jpg' }, rotation: Cesium.Math.toRadians(30) });

如果希望太阳和星空随时间连续旋转，可以直接监听 Cesium Clock 的 tick 事件：

viewer.clock.onTick.addEventListener(function(clock) { const date = Cesium.JulianDate.toDate(clock.currentTime); const hours = date.getHours() + date.getMinutes() / 60; // 一天转一圈，负号根据实际方向调整 const angle = -Cesium.Math.TWO_PI * hours / 24; viewer.scene.skyBox._rotation = angle; });

我这里写的是_rotation，因为如果只改了SkyBox.js而没有为它写 setter 方法，那么直接访问内部变量是最快的办法。如果你打算长期使用，最好在SkyBox上定义一个正式的rotation属性，内部再同步更新_rotationMatrix，这样代码会干净很多。

3.5 同步场景光照方向，不然太阳会“分裂”

如果只旋转天空盒，你会看到一个很尴尬的问题：天空贴图里的太阳已经转到西边了，但建筑物、地形的阴影还保持在上午方向。这是因为 Cesium 默认的光照方向和天空盒完全是两套逻辑。

解决办法是手动指定场景光照方向，让它跟随天空盒的旋转矩阵：

const originalSunDir = new Cesium.Cartesian3(1.0, 0.2, 0.3); const rotatedSunDir = new Cesium.Cartesian3(); viewer.clock.onTick.addEventListener(function(clock) { const angle = ...; // 与天空盒旋转角度保持一致 const rotationMatrix = Cesium.Matrix3.fromRotationY(angle, new Cesium.Matrix3()); Cesium.Matrix3.multiplyByVector(rotationMatrix, originalSunDir, rotatedSunDir); viewer.scene.lightDirection = rotatedSunDir; });

这样设置以后，场景里的地形、3D Tiles、模型的光照方向都会跟着旋转。太阳在天空盒里的位置和实体的受光面就能基本对齐，视觉上才完整。这部分内容看着不难，但极其容易被忽略，我在第五章会再展开一次真实太阳方向的计算。

4. 实战方案B：不改引擎的序列帧动态天空盒

4.1 序列帧的原理和适用边界

如果你的项目不允许改引擎源码，或者临时要出一个效果给客户看，那可以用序列帧方案。原理不复杂：提前渲染好一组六面平方图，每组对应一个时间点。比如从日出到日落，每隔一分钟渲染一帧，总共 720 帧，然后用定时器按顺序不断替换scene.skyBox的纹理源。

这个方案本质上是在用“图片序列”模拟“连续旋转”。每一帧里太阳的位置都略微偏移，连续切换时就会出现天空旋转的视觉效果。它比改源码简单得多，不碰任何底层实现，只是在 JS 层替换天空盒的资源。

但代价也很明显。720 帧乘以六张贴图，假设每张贴图 1MB，就是 4GB 以上的资源量，浏览器根本承受不了。实际项目中一般会降低到 30 帧或者 60 帧，并且每帧贴图压缩后控制在几百 KB，才勉强可接受。

4.2 用预加载图片资源实现帧切换

我这里给一个可运行的思路。先把所有帧的图片资源预加载到内存里，而不是在切换时才发起 HTTP 请求，可以大幅减少闪烁。

const FRAME_COUNT = 60; const frameImages = []; // 预加载第 i 帧的六张贴图 async function preloadFrames() { for (let i = 0; i < FRAME_COUNT; i++) { const promises = [ loadImage(`./skybox/frame_${i}_px.jpg`), loadImage(`./skybox/frame_${i}_nx.jpg`), loadImage(`./skybox/frame_${i}_py.jpg`), loadImage(`./skybox/frame_${i}_ny.jpg`), loadImage(`./skybox/frame_${i}_pz.jpg`), loadImage(`./skybox/frame_${i}_nz.jpg`) ]; frameImages.push(await Promise.all(promises)); } } function updateSkyBoxFrame(index) { const views = ['positiveX', 'negativeX', 'positiveY', 'negativeY', 'positiveZ', 'negativeZ']; const sources = {}; for (let j = 0; j < views.length; j++) { sources[views[j]] = frameImages[index][j]; } viewer.scene.skyBox = new Cesium.SkyBox({ sources: sources }); }

定时切换时，建议 8 到 12 帧每秒就已经能看出较流畅的动画，不需要 60fps。帧率太高一方面资源消耗大，另一方面 Cesium 内部每帧都在创建新的纹理资源，容易造成 GPU 内存抖动。

4.3 序列帧方案的性能优化与注意事项

序列帧方案最大的问题是每次新建SkyBox实例都会重新创建 GPU 纹理。如果每秒切换 12 次，那就是每秒创建 72 张纹理，长时间跑下来内存占用会逐渐增加。我建议：

• 控制切换频率，8fps 足够。
• 使用ImageBitmap代替HTMLImageElement，可以避免主线程解码卡顿。
• 在切换出旧帧后，手动调用相关纹理的销毁方法，或者至少置空引用，方便 GC 回收。
• 如果发现页面在摄像机大幅旋转时出现明显卡顿甚至崩溃，多半是纹理创建和销毁竞争导致，这时候需要降低切换频率，或者回到方案A。

另外，现实项目中很少会自己预渲染天空盒序列。比较常见的做法是从天气服务商购买动态天空盒视频或序列帧，或者用 Blender、Houdini 渲染好一段天穹动画后拆帧。千万不要试图从 Cesium 默认天空盒里直接抓帧，会产生接缝和畸变。

5. 动态光照同步：让太阳、阴影和天空盒“步调一致”

5.1 为什么 Cesium 默认光照和天空盒是两码事

Cesium 场景中的物体光照方向由scene.lightDirection控制。如果你不手动设置它，Cesium 会根据当前时刻和相机方位自动计算一个太阳方向。问题在于，这个自动计算用的是 Cesium 内部天文算法，和我们自己旋转天空盒贴图时的角度没有任何关联。

这就可能导致一个反直觉的现象：天空盒贴图里的太阳明明在东边，但实体模型的阴影却朝向北边。尤其在做智慧城市楼宇光影分析时，这个错误是致命的。所以动态天空盒必须和动态光照一起做，否则等于只做了一半。

5.2 手动指定光照方向

最简单的同步方法是强制设置viewer.scene.lightDirection。你可以先固定一个方向的单位向量，然后把它乘以天空盒的旋转矩阵。这样天空转到哪个角度，光照方向就跟着转到哪个角度，两者天然一致。

const baseSunDir = Cesium.Cartesian3.normalize( new Cesium.Cartesian3(-1.0, 0.4, 0.5), new Cesium.Cartesian3() ); function updateLight(rotationMatrix) { Cesium.Matrix3.multiplyByVector( rotationMatrix, baseSunDir, viewer.scene.lightDirection ); }

这段代码里的viewer.scene.lightDirection是 Cesium 的一个可写属性，设置后就会覆盖默认的自动太阳方向。地形启用光照后（viewer.scene.globe.enableLighting = true），地表亮度也会随之变化。

5.3 按真实时刻计算太阳方位

如果你的项目需要模拟真实世界某个日期、某个地理位置的太阳轨迹，可以用 Cesium 自带的Simon1994PlanetaryPositions计算太阳方向，这个 API 也是 Cesium 官方自己计算自动光照时用的：

const now = Cesium.JulianDate.now(); const sunDir = Cesium.Simon1994PlanetaryPositions.computeSunDirectionInWorld( now, new Cesium.Cartesian3() );

拿到真实太阳方向后，再叠加我们想要的时间偏移（模拟另一天的效果）或旋转矩阵，就能做到“基础方向来自真实天文计算，视觉展示上再按需求缩放和旋转”。

有一点要注意：computeSunDirectionInWorld返回的是世界坐标系下的方向，而 Cesium 的 Y 轴、Z 轴和经纬度关系需要你稍微熟悉一下才可以确定具体方位。如果发现阳光方向和经纬度对不上，检查一下是不是坐标系轴方向理解反了。

我自己实际项目里的做法是：天数影响太阳方位角，小时影响太阳高度角，然后把这两个角度组合成旋转矩阵叠加到天空盒的旋转矩阵上，再传给lightDirection。效果比单纯固定方向真实很多，复杂度也没有明显上升。

6. 常见问题与排查技巧实录

6.1 天空盒不显示，直接黑屏

这是最常遇到的问题，原因通常有三个：

第一，六张贴图有一张加载失败。Cesium 对天空盒贴图加载失败经常是静默的，控制台只报一个 404，但画面就是黑屏。建议在加载前先自己检查所有 URL 是否有有效资源。第二，贴图跨域问题。如果你的天空盒贴图放在 CDN 或 OSS 上，必须配置 CORS 跨域访问，否则 WebGL 无法读取像素。第三，修改源码方案里没把 uniform 绑定好，导致 Shader 编译报错，此时控制台会有 GLSL 编译错误日志，仔细看就会发现问题。

解决方案很简单：先任意替换成 Cesium 默认的天空盒贴图路径，如果还能显示，那就是你的贴图或 URL 问题；如果替换后也不显示，那就是代码里的 uniform 绑定或 Shader 修改有问题。

6.2 旋转后纹理拉伸、接缝错乱

天空盒纹理接缝错乱，大概率是六面的图片顺序不对。CubeMap 的 +X、-X、+Y、-Y、+Z、-Z 是有一套严格顺序的，不同工具的导出顺序可能完全不同。建议用最朴素的调试方法：准备一张各面颜色都不同的测试图，比如正X用红色、负X用蓝色，然后顺时针去看，确认每张贴图应该放在哪个面上。

旋转后出现轻微拉伸则一般发生在textureCube采样边界。处理方法是在采样前把方向向量 normalize，并保证旋转矩阵用的是规范正交矩阵。Cesium 的Matrix3.fromRotationY生成的是标准旋转矩阵，不会有比例拉伸问题。

6.3 光照方向始终对不上

如果你已经设置了viewer.scene.lightDirection，但太阳光看起来还是不对，很可能是光照方向向量没有单位化，或者旋转矩阵和天空盒旋转矩阵不是同一个。因为lightDirection在实际计算中会被归一化，所以长度问题不大，关键是两个矩阵要严格一致。

另外，3D Tiles 的光照方向可能在数据本身的法线贴图上有特殊设置，不排除个别模型法线烘焙固化，导致阴影和实时光照不一致。这种情况和天空盒无关，属于模型制作问题。

6.4 摄像机大幅旋转时出现卡顿甚至崩溃

动态天空盒本身不会导致这种问题，但如果用序列帧方案，在摄像机旋转时高频新建 SkyBox 对象，确实可能因为纹理创建竞争导致崩溃。我遇到过几次在 3D 地球快速滚动缩放时，页面直接卡死的情况，排查下来都是因为序列帧切换时创建了一张无效的ImageBitmap，导致后续 Cesium 内部纹理对象状态错乱。

解决方案是：

• 不要每帧都调用new Cesium.SkyBox()，至少间隔 80ms 以上。
• 预加载所有帧，不要在切换时才异步请求图片。
• 如果必须在旋转过程中平滑切换，尽量升级到方案A，让 GPU 只计算一个矩阵乘法，不涉及纹理重建。

6.5 真机性能表现

改源码方案的性能开销几乎可以忽略。加了一个 3x3 矩阵乘法和一次 normalize，这在中低端手机 GPU 上也是很小的工作量。真正影响帧率的往往是场景模型数量和地形瓦片加载，天空盒旋转本身不会成为性能瓶颈。

序列帧方案则要非常谨慎。我测试过 15fps 切换六张 1024x1024 的 JPEG，在中端笔记本上勉强流畅，在手机上是明显有卡顿感的。如果需要移动端展示，建议把贴图压缩到 512x512，并把切换频率降到 10fps 以下，不然功耗和显存占用都会很难看。

6.6 常见问题速查表

为了方便后面排查，我把这几个高频问题整理成一张表：

个人体会是，动态天空盒最大的难点不在 Shader 或矩阵，而在问题定位：画面不对时你很难一眼看出是贴图问题、矩阵问题还是光照问题。所以建议一开始就把天空盒旋转和光照同步做成一个独立的模块，单独调试通过后再集成到业务场景里，别等整个场景都加载完再排查。最后再分享一个小技巧：如果只需要在某个时间段做快速验证，可以先写死一个小的旋转角度，比如rotation: Cesium.Math.toRadians(15)，确认天空背景变化无误后，再接入 Clock 或真实天文算法。这样能把变量隔离到最小，踩坑的概率会低很多。