这篇笔记解决什么问题

这个 Demo 现在故意做得很克制,不是因为功能想不到,而是因为我们需要先拿到一个稳定、可反复验证的 Cesium 初始化基线。

之前往页面里叠加扫描圈、点位和联动面板之后,运行过程中出现过 Maximum call stack size exceeded。在这种情况下,继续往上堆功能会让问题越来越难拆,所以这里先把目标收敛为一件事:

  • 让真实的 Cesium Viewer 在 Demo 详情页里稳定初始化
  • 保证路由切换和组件卸载时能干净销毁
  • 保留内容壳和运行时代码分离的页面结构

当前实现怎么拆

当前这条链路分成两层:

  • content/demos/*.md 负责 Demo 页面元数据和“怎么观察效果”的轻量说明
  • demos/**/*.js 负责真正的浏览器运行时逻辑

这样做的好处是,Demo 页可以继续承担展示入口和内容壳,而重型 3D 初始化逻辑仍然留在客户端按需加载,不会把 SSR 页面也拖进浏览器专属依赖里。

运行时的关键选择

1. 使用 ESM import 初始化 Cesium

这个 Demo 直接通过 ESM 方式加载 Cesium,而不是再额外挂一套传统脚本注入逻辑。这样做有两个好处:

  • 依赖边界更清楚,运行时和工程构建保持一致
  • 以后继续加功能时,更容易沿用模块化拆分方式

2. 静态资源继续预先复制

虽然运行时代码走 ESM,但 Cesium 仍然需要它自己的静态资源目录。当前策略是继续通过 prepare:cesium 把这些资源复制到 public/cesiumStatic,这样运行时能稳定访问 WorkersAssetsWidgets

这个点很重要,因为很多“看起来像初始化失败”的问题,本质上不是 Viewer API 本身的问题,而是静态资源路径没准备好。

3. 底图先走最稳妥路线

为了保证没有 token 的情况下也能稳定显示,当前版本优先使用 Cesium 自带的基础纹理资源,不把 Demo 的可运行性绑定到外部服务授权状态上。

这意味着它不是一个追求“最好看”的版本,而是一个追求“最稳定、最容易定位问题”的版本。

为什么先回到最小版本

这个 Demo 当前最重要的价值,不是展示复杂业务能力,而是作为后续迭代的安全起点。

如果基础初始化都不稳定,那么后面再加:

  • 扫描圈
  • 飞线
  • 点位
  • 联动面板
  • 自定义镜头节奏

这些能力时,很难判断问题到底出在哪一层。先把基线做小,后续每次新增能力时都能更明确地验证“是哪一步把稳定性打破了”。

后续怎么继续加

比较稳妥的节奏是按层往回加,而不是一次性恢复全部效果:

  1. 先加单一图层或单一实体能力
  2. 再加交互或面板联动
  3. 最后再回到更完整的可视化编排

这样每一步都有明确的回退点,也更适合作为作品集里的长期维护 Demo。