企业官网建设流程全解析

做卫星轨迹可视化这个需求，我是被一个科普大屏项目带进坑的。当时要求在地球上实时显示某颗低轨卫星的运行轨迹，数据要准、画面要顺、还得能回放。一开始我天真地以为“调个接口、画条线”就完事了，结果从 TLE 数据源获取、坐标系转换到 Cesium 里动态采样，每一步都有隐藏的坑。这套流程我从零趟完后，把完整链路和排错经验整理成一份保姆级教程，适合刚接触 Cesium 的 GIS 前端、做数字孪生和航天科普的开发者，以及想搞清楚“TLE 到底怎么变成地球上那条线”的爱好者。

先说结论：卫星轨迹可视化本质上是“TLE 轨道根数 → 轨道传播算法 → 地固系坐标 → Cesium 时间轴动画”这一条链路的工程化落地。技术栈主要就是 CesiumJS 加 satellite.js，核心难点不在渲染，而在于时间系统和坐标系的理解。下面按完整流程讲。

1. TLE 数据源解析：从两行字符到真实轨道参数

1.1 去找谁拿 TLE 数据

TLE（Two-Line Element Set，两行根数）是 Norad 发布的一套轨道参数格式，网上公开源很多。我自己常用的有两个：

• CelesTrak（www.celestrak.org）—— 免费、无需注册、更新及时，有按卫星群分类的下载接口。
• Space-Track（www.space-track.org）—— 官方数据源，需要注册账号并申请 API Key，适合做自动维护。

如果你只想快速演示，CelesTrak 的GP接口就够了。比如获取国际空间站（ISS）的 TLE，直接访问：

https://celestrak.org/NORAD/elements/gp.php?GROUP=stations&FORMAT=tle

这个链接返回的是纯文本，包含多颗卫星的记录，每条记录由“卫星名称 + 两行数据”组成。也可以用CATNR=25544这样的参数单独过滤某颗卫星，返回格式默认就是 TLE。

如果你是代码里拉取，建议写个简单的脚本缓存数据。我常用的 Python 脚本长这样：

import urllib.request URL = "https://celestrak.org/NORAD/elements/gp.php?GROUP=stations&FORMAT=tle" def fetch_tle(): req = urllib.request.Request(URL, headers={"User-Agent": "Mozilla/5.0"}) with urllib.request.urlopen(req, timeout=10) as resp: return resp.read().decode("utf-8") if __name__ == "__main__": text = fetch_tle() with open("tle.txt", "w") as f: f.write(text) print("TLE saved, length:", len(text))

这里有几个小细节。一是请求头要带User-Agent，某些服务器会拦截空 UA；二是数据要缓存到本地文件或内存里，不能每次前端页面刷新都去拉远程接口，否则高频请求很容易被限流；三是如果做长期展示，建议每天定时拉一次，因为 TLE 是会过期的。

1.2 读懂 TLE 两行数据的核心字段

TLE 不是给人类看的，但你要是完全不懂它，后面报错时根本无从下手。拿 ISS 的一条 TLE 举例：

ISS (ZARYA) 1 25544U 98067A 24001.50000000 .00016717 00000-0 30550-3 0 9999 2 25544 51.6400 210.0000 0005773 150.0000 300.0000 15.49819051450000

第一行第一列固定是1，接着是卫星编号（25544）；U表示公开数据；98067A是国际代号，表示 1998 年发射、当年第 67 个任务。第一行比较重要的是第 19 到 32 列的“历元时间”，格式是YYDDD.DDDDDDDD，即“年份 + 年积日 + 日内小数时间”。

第二行才是画轨道真正要用的数据：

这些参数加上历元，就完整描述了一个 Kepler 轨道。关键是：TLE 描述的是“某个时刻”的轨道状态，不是永久有效的。TLE 更新越久，误差越大。ISS 这种大气阻力明显的低轨卫星，一般几小时到一两天就应该更新一次；单纯用几个月前的 TLE 去画轨迹，位置可能偏出去几十公里甚至更远，展示粗线条没问题，做精细对位就露馅了。

TLE 的解析我强烈建议不要自己写正则，直接用satellite.js库，两行记录传进去就给你算好所有轨道参数，省去校验位的麻烦。解析代码稍后统一给。

2. 从 TLE 到三维坐标：SGP4 传播模型与坐标系转换

2.1 为什么用 satellite.js 而不是自己手算

TLE 用的是所谓的“一般摄动模型”，它假设轨道在短时间内变化不大，然后把地球非球形引力、大气阻力、太阳光压等干扰用平均量近似。真正的轨道预报算法叫 SGP4/SDP4，SGP4 用于近地轨道（周期小于 225 分钟），SDP4 用于深空轨道。

这里面的数学推导非常复杂，涉及各种微扰项、周期项、长期项。手写完全没必要，直接用社区广泛验证过的satellite.js，它是 CelesTrak 官方推荐的一个 JavaScript 移植版本。

安装方式老样子：

npm install satellite.js

如果你不想用打包工具，也可以直接用 CDN 引入：

<script src="https://cdn.jsdelivr.net/npm/satellite.js@5.0.0/dist/satellite.min.js"></script>

引入后在浏览器全局就能拿到satellite对象。

2.2 完整解算流程：解析、传播、坐标转换

先看核心代码。假设你已经从上面的接口拿到了 TLE 文本，并且人工分割出了卫星名称和两行数据：

// 引入 satellite.js（ESM 或全局变量都行） import * as satellite from 'satellite.js'; // TLE 两行数据 const tleLine1 = '1 25544U 98067A 24001.50000000 .00016717 00000-0 30550-3 0 9999'; const tleLine2 = '2 25544 51.6400 210.0000 0005773 150.0000 300.0000 15.49819051450000'; // 1. 解析 TLE，得到轨道参数对象 satrec const satrec = satellite.twoline2satrec(tleLine1, tleLine2); // 2. 用某个时间点去传播轨道，得到卫星在该时刻的方位 const date = new Date(); const positionAndVelocity = satellite.propagate(satrec, date); // 如果返回的位置是 null/undefined，说明 TLE 或时间有问题 if (!positionAndVelocity.position) { throw new Error('卫星位置计算失败，请检查 TLE 格式或传播时间'); } // 3. 将 TEME 惯性系坐标转换为 ECEF 地固系坐标 // 这一步必须做，因为 Cesium 的地球模型是跟随自转的 const gmst = satellite.gstime(date); const positionEcf = satellite.eciToEcf(positionAndVelocity.position, gmst); // 4. 转成 Cesium 的 Cartesian3（注意单位：TLE 输出是 km，Cesium 用 m） const cartesian = new Cesium.Cartesian3( positionEcf.x * 1000, positionEcf.y * 1000, positionEcf.z * 1000 );

twoline2satrec做了 TLE 解析和数据校验，返回的satrec对象包含了轨道六根数以及 SGP4 算法需要的内部参数。propagate是核心，它接受一个 JavaScriptDate对象，返回该时刻的 TEME 坐标系位置和速度向量。

这里最容易踩的坑是单位。satellite.js返回的位置单位是千米，而 Cesium 中默认所有坐标单位是米。如果忘了乘 1000，画出来的卫星会直接钻进地心，表现就是屏幕上什么都看不到，或者轨迹缩成一团。

还有一个大坑是时间。propagate接收的时间必须是标准的 UTC 时间，JavaScript 的new Date()本身是 UTC 时间戳，传给它是安全的。但千万不要把 Cesium 里的JulianDate直接传给propagate，两者不是同一种对象。正确姿势是：Cesium 的JulianDate用JulianDate.toDate()转成 JSDate，再传给satellite.js。

2.3 为什么一定要从惯性系转到地固系

这个问题值得细说。satellite.js的propagate返回的是 TEME 坐标系（一种地心惯性系，约等于 J2000 系加上岁差章动近似）。在这个坐标系里，卫星的位置是相对“固定星空背景”的，也就是说地球在它下面旋转。

但在 Cesium 里，地球模型是一个旋转的三维椭球体，你可以把地球想象成“实时自转”的。如果你直接把 TEME 坐标当成 Cesium 坐标，画出来的卫星轨迹会“相对于星空不动”，而地球在底下转，最终表现就是卫星轨迹整体拧成麻花，完全对不上真实地面。

所以一定要用satellite.gstime(date)算出格林尼治恒星时角 GMST，再调用satellite.eciToEcf(position, gmst)，把惯性系坐标旋转到地球固连系坐标。旋转完之后，得到的坐标轴与 Cesium 的坐标轴也是对齐的：X 指向本初子午线，Z 指向北极，Y 满足右手定则。这一点 Cesium 的Cartesian3和 ECEF 坐标系是天然一致的，所以后面的转换非常顺畅。

如果你要做的是“卫星相对地面站”的应用场景，这个转换更是逃不掉，否则你连仰角方位角都没法算。总之，坐标系转换不是可选项，而是必选项。

3. Cesium 可视化落地：卫星本体、轨迹线与星下点

3.1 时钟和时间轴要一开始就规划好

很多初学者在 Cesium 里画卫星，第一反应是开个requestAnimationFrame，每帧去算一个新位置然后entity.position赋值。这种方案能转，但问题一大堆：你没法拖动时间轴回放，动画步长不均匀，时间一长还容易性能崩。

正确做法是把卫星位置做成时间采样数据，交给 Cesium 的时钟系统去驱动。这样好处很明显：时间轴想拖哪拖哪，系统自动插值，动画秒变顺滑。

Viewer 初始化和时钟配置大概是这样：

const viewer = new Cesium.Viewer('cesiumContainer', { // 关闭默认的实体点击拾取气球 selectionIndicator: false, // 关闭动态云层等遮挡 terrainProvider: new Cesium.EllipsoidTerrainProvider(), }); // 设定时间范围：前 1 小时到后 1 小时 const start = Cesium.JulianDate.fromDate(new Date(Date.now() - 3600 * 1000)); const stop = Cesium.JulianDate.fromDate(new Date(Date.now() + 3600 * 1000)); viewer.clock.startTime = start.clone(); viewer.clock.stopTime = stop.clone(); viewer.clock.currentTime = start.clone(); viewer.clock.clockRange = Cesium.ClockRange.LOOP_STOP; // 循环播放 viewer.clock.shouldAnimate = true; // 自动播放 // 让时间轴聚焦到该时间范围 viewer.timeline.zoomTo(start, stop);

clockRange我建议设成LOOP_STOP，这样时间到终点后自动从头循环，适合大屏展示。如果你想要“一次播放完就停在终点”，就用CLAMPED。

3.2 采样位置数据并抬起卫星实体

准备好时钟后，我们把卫星在未来一小时内的轨迹全部提前算好，放进SampledPositionProperty。采样间隔根据你想展示的时间跨度来定。示例里跨 2 小时，10 秒采样一次，共 720 个点，足够 Cesium 做平滑插值，也不会太吃内存。

// 创建采样位置属性 const positionProperty = new Cesium.SampledPositionProperty(); // 按 10 秒间隔采样 const intervalSeconds = 10; const totalSeconds = 3600 * 2; for (let offset = 0; offset <= totalSeconds; offset += intervalSeconds) { const time = new Date(start.toDate().getTime() + offset * 1000); const pv = satellite.propagate(satrec, time); if (!pv.position) continue; const gmst = satellite.gstime(time); const ecf = satellite.eciToEcf(pv.position, gmst); const position = new Cesium.Cartesian3(ecf.x * 1000, ecf.y * 1000, ecf.z * 1000); positionProperty.addSample(Cesium.JulianDate.fromDate(time), position); }

这里有个提升性能的小技巧：propagate里其实做了很多次三角函数计算，720 次循环不算什么，但如果你要同时画几十颗卫星、采样密度又高，那就该考虑用 Web Worker 离线计算，算完再传给主线程。后面排错章节会再讨论。

接着创建卫星实体。最省事的组合是：model显示 3D 模型 +path画轨迹 +label显示名字 +point作为后备显示。

const satelliteEntity = viewer.entities.add({ position: positionProperty, point: { pixelSize: 8, color: Cesium.Color.WHITE, }, label: { text: 'ISS', font: '14px sans-serif', pixelOffset: new Cesium.Cartesian2(0, -20), fillColor: Cesium.Color.WHITE, showBackground: true, backgroundColor: Cesium.Color.fromCssColorString('#000000').withAlpha(0.6), }, path: { resolution: 600, leadTime: 3600, trailTime: 3600, material: new Cesium.PolylineGlowMaterialProperty({ glowPower: 0.2, color: Cesium.Color.CYAN, }), width: 2, }, }); // 如果加载 glTF 模型 const modelPromise = Cesium.Model.fromGltfAsync({ url: '/data/satellite.glb', scale: 0.01, minimumPixelSize: 64, }); satelliteEntity.model = modelPromise;

path里的leadTime和trailTime表示轨迹向前/向后延伸的时间长度，单位是秒。我这里设为前后各一小时，正好覆盖采样范围。

关于模型朝向，强烈建议给实体加orientation，否则模型会一直保持初始朝向，看起来非常出戏：

satelliteEntity.orientation = new Cesium.VelocityOrientationProperty(positionProperty);

VelocityOrientationProperty会根据位置采样数据自动计算速度方向，把模型朝向设置成顺着运动方向。这个属性对model、billboard都有效。

3.3 星下点轨迹与视角跟随

星下点（地面投影点）是一个很常见的附加元素。实现方式有两种。

第一种是用CallbackProperty动态计算当前时刻卫星的经纬度，再把点固定在地表：

const groundPosition = new Cesium.CallbackProperty(() => { const time = viewer.clock.currentTime; const cartesian = positionProperty.getValue(time); if (!cartesian) return undefined; const carto = Cesium.Cartographic.fromCartesian(cartesian); return Cesium.Cartesian3.fromRadians(carto.longitude, carto.latitude, 0); }, false); viewer.entities.add({ position: groundPosition, point: { pixelSize: 6, color: Cesium.Color.RED, }, });

第二种是采样时同时算地面投影点，一次性塞进SampledPositionProperty。我推荐第二种，性能更好，因为CallbackProperty在每帧渲染时都会执行一次回调，卫星数量一多就比较吃力。

让视角跟随卫星最简洁的方式是：

viewer.trackedEntity = satelliteEntity;

设置之后 Cesium 会自动让相机一直盯着卫星。但这里有个体验注意点：低轨卫星速度很快（大约每秒 7 公里多），相机默认跟随可能会让人有明显眩晕感。我在项目里常做的是手动控制相机高度：

viewer.clock.onTick.addEventListener(() => { const pos = positionProperty.getValue(viewer.clock.currentTime); if (!Cesium.defined(pos)) return; const hpr = new Cesium.HeadingPitchRoll( 0, Cesium.Math.toRadians(-30), 0 ); viewer.camera.lookAt(pos, hpr); });

这样就能固定一个俯视角，保持卫星始终居中，屏幕上的 GIS 信息不至于晃得太厉害。

4. 高频报错排查：跨域、NaN 坐标与模型姿态

4.1 数据加载报错：Request failed with status 404 / CORS

最常见的第一个报错就是 TLE 文件加载失败。我在本地调试时喜欢直接双击index.html打开页面，结果 Cesium 对file://协议限制非常严格，所有通过Resource发起的请求都会因为 CORS 跨域被浏览器拦截。

解决思路有三种，按优先级排列：

• 把 TLE 文本直接写成 JavaScript 字符串内联在代码里。适合演示和小范围使用。
• 用本地开发服务器起静态服务（比如npx serve、http-server或 Vite Dev Server），让页面和 TLE 文件同源。
• 搭一个轻量代理接口，后端去抓 CelesTrak，前端只请求自己的后端，从根上规避跨域。

如果你硬要用fetch去拉远端 TLE，一定要确认目标服务器是否允许 CORS。CelesTrak 本身是允许跨域的，但某些镜像源不一定；Space-Track 经常因为权限或者请求头问题报 401，需要在代码里带好认证信息。

真正排查时先看浏览器 Network 面板，确认请求是直接失败还是返回了异常状态码。如果请求状态是 200 但 Cesium 报错，那大概率是 TLE 文本格式解析问题。比如文件开头带 BOM、空行、Windows 的\r\n换行符，都会干扰按行分配的逻辑。我的解析循环一般会先做清洗：

const lines = tleText .split(/\r?\n/) .map(l => l.trim()) .filter(l => l.length > 0);

4.2 卫星消失、坐标 NaN 或跑到地心去

如果你打开页面后整颗卫星不见，或者实体的轨迹乱七八糟，多半是三个原因之一。

第一，TLE 解析失败，satrec里相关参数是 NaN。这种情况通常发生在 TLE 行没有正确配对时，比如你把某颗卫星的名称行当成了 TLE 行，或者剪切时少了末尾空格导致校验位错位。satellite.js的twoline2satrec对格式比较宽容，但如果传入的两行不是严格的 TLE 行，它会得到奇怪的结果。排查时打印一下satrec就能看出来。

第二，传播时间超出合理范围。TLE 是一个预报模型，越是远离历元时间，计算结果越不可靠。如果你把时钟范围设到距今 100 年，satellite.js在某些极端时间点可能返回NaN。我的处理是在采样循环里做一次防护：

const pv = satellite.propagate(satrec, time); if (!pv.position || isNaN(pv.position.x) || isNaN(pv.position.y) || isNaN(pv.position.z)) { continue; }

跳过这些坏点，不要让采样数据里混入NaN。

第三，单位搞错。位置单位是千米，忘了乘 1000，卫星就钻到地心附近，看起来像消失了一样。这个我在第 2.2 节已经强调过，但它在实际项目里是最容易被忽视的，遇到问题第一反应就查单位。

还有一个程序源导致的坑：SampledPositionProperty.addSample要求加入的采样时间必须单调递增。如果你循环里时间推进写成了offset += intervalSeconds，没问题；但如果你用while (time < stop)然后又对time做了不干净的修改，可能出现两个相同时间戳的采样点，Cesium 会直接抛DeveloperError: Expected value to be greater than or equal to 0。

4.3 模型姿态乱转：朝向和坐标系的问题

模型朝向不对是最容易劝退新手的视觉问题。症状是：卫星模型在太空里“乱滚”，或者垂直于运动方向横着飞。

这种情况首先检查orientation。如果没有设置VelocityOrientationProperty，模型会按照 Cesium 默认的局部坐标系摆放，而 glTF 模型内部又可能有自己的轴定义，两者叠加起来什么古怪角度都可能出现。加了VelocityOrientationProperty之后，模型会沿速度方向对齐，但 glTF 本身的前向轴通常是 Y 轴或 Z 轴，如果模型本身朝 X 轴，那就得在建模型时就调整好，或者传入一个固定的旋转矩阵做补偿。

我之前遇到一个比较隐蔽的情况：模型在自己电脑上方向是对的，一到客户的大屏服务器上就偏了。后来发现是不同版本 Cesium 对VelocityOrientationProperty的默认朝向约定有细微变化。所以如果你的项目固定了 Cesium 版本，别轻易升级，升级后动画代码要重新过一遍。

4.4 轨迹线锯齿、闪烁和穿地问题

轨迹线看着发虚或者一闪一闪，通常和两个因素有关。

一是线宽。WebGL 对polyline线宽的支持在不同显卡、不同浏览器上不一致，很多环境最大只支持 1 像素。所以你在代码里把width设为4，在某些平台上也不一定生效。我的做法是用PolylineGlowMaterialProperty，它靠发光效果来增强视觉厚度，对线宽的实际依赖会小一点。如果线条实在细得没法看，改用带宽度的PolylineCollection也能解决。

二是轨迹穿过地球内部。低轨卫星绕地球一圈时，轨迹线会自然地从地球背面绕过，你如果开了地形或把path的范围拉得很大，可能看到一段线被地球遮挡，产生闪烁或者“切断”的感觉。这是因为轨迹线始终是三维空间中的线段，它不是贴着地表走的。解决办法是不要开太强的景深或抗锯齿，或者用depthTestAgainstTerrain配合透明度处理。对于纯展示场景，一般不做特殊处理问题也不大，因为线段本身就在卫星真实高度上。

大概率的出现场景是在2D或2.5D模式下，Cartesian3坐标点在地球背面时造成的渲染异常。切换到3D模式基本就好了。

4.5 采样密度过高导致页面卡死

最后聊一个性能问题。有人为了轨迹平滑会设成每秒采样一个点，跨两小时就是 7200 个点，如果同时画 20 颗卫星，那就是 14.4 万个采样点，再叠加轨迹和历史路径，帧率不崩才怪。

我踩过坑之后的经验是：先想清楚你要展示的时间尺度和空间尺度。大屏展示低轨卫星 2 小时轨迹，采样间隔 10-15 秒完全够用；但如果做高精度轨道对接演示，那就不光要加密采样，还应该用更精确的数值积分模型，TLE + SGP4 就不一定胜任了。

性能调优的另一个方向是离线计算加按需更新。前端每次启动时，把未来几小时的轨迹一次性算好，数量大就挪到后端算成一个 GeoJSON 或二进制文件，前端只负责读取回放。不要在前端做实时的大规模轨道预报，性价比太低。

这条链路还能继续扩展

把 TLE 数据源到 Cesium 轨迹可视化这条链路跑通之后，你会发现它是一套可以复用的地基。多卫星同时展示、卫星与地面站通讯连线、覆盖范围计算、传感器扫描体可视化，都是在这个骨架之上扩展的。我个人体会是，前期花时间把坐标系和时间系统理解透，比急着调 UI 重要得多。后面每一个扩展功能，回归到的仍然是那几个基础点：数据准不准、时间对不对、坐标系转没转。

最后分享一个小技巧：如果只是临时想看某颗卫星的轨迹对不对，可以先在 CelesTrak 页面用它的在线地图对比一下，再去调 Cesium 里的代码。把“地图上的正确轨迹”作为参照，能省掉大量排查时间。轨迹对上了，再叠加模型、标签、星下点这些视觉层。先把地基夯实，后面加需求心里才不慌。