Appearance
Cesium 升级清单 + 回归矩阵
面向
@nexa/gis-cesium的 Cesium 版本升级专用流程与回归基线。 通用依赖变更流程见 dependency-checklist.md；本文聚焦 Cesium 私有 API 兼容面与版本敏感能力。
当前锁定版本（2026-08 实测）
| 包 | 声明 | 解析版本 | 说明 |
|---|---|---|---|
| cesium | ^1.133.1 | 1.133.1 | peer + dev，SDK 不直接打包 |
| @cesium/engine | 传递 | 20.0.1 | Cesium 运行时核心 |
| @cesium/widgets | 传递 | 13.1.1 | Viewer/Timeline 等控件 |
| dayjs | ^1.11.19 | 1.11.19 | 时间工具 |
| satellite.js | ^6.0.2 | 6.0.2 | TLE 轨道计算 |
| cesium-heatmap-es6 | ^0.8.0 | 0.8.0 | 热力图 |
| @turf/turf | ^7.3.5 | 7.3.5 | 地理计算 |
| ol | ^10.10.0 | 10.10.0 | peer + dev，Overlay 混用 |
| vue | ^3.5.21 | 3.5.21 | peer + dev，宿主全局集成 |
私有 API 表面矩阵
SDK 通过私有/内部 API 访问 Cesium 的具体点。升级前逐项核对，升级后逐项回归。
| # | 家族 | 成员 | 位置 | 状态 |
|---|---|---|---|---|
| ① | Material._materialCache | getMaterial / addMaterial / Material[type+'Type'] 静态量 | core/cesium-compat/materialCache.ts 适配层 + 6 个消费文件 | ✅ 适配层收口（P2-A W1） |
| ② | Property 静态量 | isConstant / equals / getValueOrClonedDefault / createPropertyDescriptor | viewerToolMixin.ts Material1 4 处 | ✅ 已迁移 propertyUtils + shim createPropertyDescriptor（P2-B1） |
| ③ | Timeline | currentTime / makeLabel | viewerToolMixin.ts / viewerScenarioConfigMixin.ts | ✅ 类型 shim（P2-A W2） |
| ④ | ClockViewModel | Viewer._clockViewModel | viewerAnimationPanelMixin.ts 5 处 | ✅ 类型 shim（P2-A W2） |
| ⑤ | Scene 内部 | ~18 处引擎内部字段/构造 | viewerOffscreenRenderMixin.ts 5 / createFrameBuffer.ts 2 等 | ✅ shim 具型精化完成（P2-B1）：any → 具型形状，_hdr 以公开 highDynamicRange 替换，冗余强转清零 |
| ⑥ | Framebuffer/Texture 构造器 | new Framebuffer(...) / new Texture(...) | createFrameBuffer.ts | ✅ 构造器已入 shim（P2-B1），冒烟覆盖（c） |
| ⑦ | Camera 静态量 | DEFAULT_VIEW_RECTANGLE / FACTOR | AirViewer.ts 保存/还原守卫 + viewerScenarioConfigMixin.ts 等 | ✅ AirViewer 构造时快照、destroy 时还原（P2-B2）；dts 安全；销毁协议冒烟（f） |
| ⑧ | Model | _runtimeNode | viewerNodeToTransformMixin.ts 等 | 待 P2-B2（普通 as 断言，0 grep，无公开替代） |
| ⑨ | Entity._type / Viewer._element | — | 各处 | 已局部 shim / 不计入 grep |
此外
core/host.ts经getHostCesium/getHostVue/getHostEcharts/getHostOl收口的宿主库 UMD 全局强转（echarts/ol 各 1 处）保留——它们面向宿主集成点，不是 Cesium 私有 API。
grep 回归门禁
私有 API 访问点计数快照，只许下降、不许反弹：
bash
grep -rn "as unknown as\|@ts-expect-error\|@ts-ignore" packages/gis-cesium/src/lib | wc -l| 阶段 | 计数 |
|---|---|
| P1 基线 | 59 |
| P2-A 完成（适配层 + 类型 shim） | 38 |
| P2-B1 完成（Scene shim 精化 + Property 静态量迁移） | 26 |
| P2-B2 完成（viewer 销毁协议 + 资源单例统一 + 散点收口） | 24 |
| P3 前 | 只降不升 |
版本敏感能力 → 回归覆盖映射
| 能力 | 依赖的私有/内部面 | 自动化覆盖 | 升级时人工检查 |
|---|---|---|---|
| 自定义材质注册 | Material._materialCache | 冒烟 a：getMaterial('PolylineTrail'/'RadarWave'/'RadarWaveGradient') truthy | 材质视觉无回归 |
MaterialProperty/fromType | _materialCache + fabric 结构 | 冒烟 b：new FlowingPolylineMaterialProperty() + fromType 非空 | 三类连接线正常 |
| 离屏渲染/FBO | Framebuffer/Texture 构造器 | 冒烟 c：viewerOffscreenRenderMixin + createFrameBuffer + renderToCanvas no-throw | 离屏示例清晰 |
| 相机飞行 | Camera API | 冒烟 d：camera.flyTo no-throw | 各 flyTo 示例正常 |
| Material1 + TLE 轨道 | window.Cesium.Material1 宿主全局 | 冒烟 e：viewerToolsMixin → Material1 定义 + tleSatelliteTrack 建实体 | TLE 轨道示例正常 |
| 时间控件 | Timeline / _clockViewModel | 单测（shim 编译保证） | 动画面板交互正常 |
| viewer 销毁协议 | Camera 静态量 + mixin uninstall 钩子 | 冒烟 f：extend 注册钩子 → destroy → 钩子执行 + Camera.DEFAULT_VIEW_RECTANGLE 同一性还原 | 各 mixin destroy 后无残留监听 / primitive |
冒烟套件：pnpm --filter @nexa/gis-cesium run test:e2e（Playwright 无头 Chromium，见 [P2-A 实现]）。
升级 SOP（顺序执行）
bash
# 1. 依赖变更（含 lockfile diff 审阅 @cesium/engine / @cesium/widgets 透传）
pnpm add cesium@<new> --filter @nexa/gis-cesium
# 2. 双包类型检查（关键：残留未使用 @ts-expect-error 会在此暴露）
pnpm --filter @nexa/gis-cesium run typecheck
pnpm --filter @nexa/scenario-data run typecheck
# 3. 单元测试 + 库构建
pnpm --filter @nexa/gis-cesium run test
pnpm --filter @nexa/gis-cesium run build:lib
# 4. 全仓 lint（0 error 门禁）
pnpm exec eslint . --ignore-pattern "**/dist-app/**"
# 5. grep 快照（必须 ≤ 38 且不反弹）
grep -rn "as unknown as\|@ts-expect-error\|@ts-ignore" packages/gis-cesium/src/lib | wc -l
# 6. 浏览器冒烟（真实 Viewer + WebGL）
pnpm --filter @nexa/gis-cesium run test:e2e
# 6b. 裸 viewer 消费者销毁提醒：经 destroyViewer(viewer) 触发 mixin 的 uninstall 钩子，
# 勿 monkey-patch Cesium.Viewer.destroy（SDK 不覆盖原生销毁路径，见架构文档「viewer 销毁协议」）
# 7. 更新本文档：锁定版本表、私有 API 矩阵状态、grep 快照升级后 shim 清理
Cesium 升级若上游 .d.ts 已声明 shim 成员，须删除对应 shim 文件中的同名增强（否则重复成员冲突）。两处 shim 分工：
packages/gis-cesium/src/lib/cesium.d.ts（Viewer extensions + _clockViewModel/Timeline，P2-A）：
Viewer._clockViewModel（私有 shim，JSDoc 已标注）Timeline.currentTime/makeLabel
packages/gis-cesium/src/types/cesium-internal.d.ts（Scene 内部面 + 构造器/静态量，P2-B1）：
Scene._defaultView/_view/_frameState/_shadowMapCamera/_computeCommandList/_overlayCommandList/context/updateFrameState/updateAndExecuteCommands/resolveFramebuffersPostProcessStageCollection.hasSelected/Fog.update（interface 增强，公开类已有成员会静默忽略）Framebuffer/Texture构造器 +createPropertyDescriptor+Cesium3DTilePass命名空间（运行时公开、dts 未声明）- 逐项对照上游 CHANGES.md 是否公开了这些成员